​
Customers

The Customers feature provides a centralized registry for your users. By linking payments to customer profiles, you unlock unified analytics, personalized communications, and streamlined recurring billing.
Creating customers is optional. Payments can be processed without them, but linking payments to customers enables powerful features like lifetime value tracking and automated email workflows.

​
🎯 Why Use Customer Profiles?

BenefitDescription
Unified HistorySee all payments, subscriptions, and invoices for a single customer in one place.
Lifetime Value (LTV)Automatically track how much revenue each customer has generated.
Personalized WorkflowsUse customer data in Workflows to send targeted emails.
Faster CheckoutStore customer details to pre-fill checkout forms for returning users.

​
🛠️ Creating a Customer

​
Via SDK

import { Reevit } from '@reevit/node';

const customer = await reevit.customers.create({
  external_id: 'usr_1234', // Your internal user ID
  email: 'ada@example.com',
  name: 'Ada Lovelace',
  phone: '+233501234567',
  tags: ['premium', 'early-adopter'],
  metadata: { plan: 'pro', signup_source: 'referral' }
});

​
Linking a Payment to a Customer

When creating a payment, include the customer_id: 
await reevit.payments.createIntent({
  amount: 15000,
  currency: 'GHS',
  customer_id: customer.id, // Link to customer profile
  // ...
});

​
📋 Field Reference

FieldTypeRequiredDescription
external_idstringYour internal identifier for this customer (e.g., your database user ID).
emailstringCustomer’s email address. Used for receipts and workflow triggers.
phonestringCustomer’s phone number in E.164 format.
namestringFull name or display name.
tagsstring[]Labels for segmentation (e.g., ["vip", "newsletter"]).
metadataobjectAttach arbitrary key-value pairs for your own tracking.

​
📊 Customer Analytics

The customer profile automatically aggregates:
  • Total Spent: Sum of all successful payments.
  • Payment Count: Number of transactions.
  • Last Payment Date: When they last paid.
  • Subscription Status: Active/cancelled recurring plans.
Fetch a customer’s payment history: 
const history = await reevit.customers.getPaymentHistory('cus_xyz123');
// [
//   { 
//     payment_id: 'pay_001', 
//     amount: 5000, 
//     status: 'succeeded', 
//     source: 'payment_link',
//     source_description: 'Premium Plan Checkout',
//     created_at: '...' 
//   },
//   { 
//     payment_id: 'pay_002', 
//     amount: 10000, 
//     status: 'succeeded',
//     source: 'api',
//     created_at: '...' 
//   }
// ]
Find your top customers by revenue: 
const topCustomers = await reevit.customers.getTopCustomers({ limit: 10 });

​
🔍 Payment Source Tracking

Each payment in a customer’s history includes source information to help you understand where payments originated:
FieldDescription
sourceThe origin type: payment_link, api, or subscription
source_idThe ID of the source (e.g., payment link ID, subscription ID)
source_descriptionHuman-readable name (e.g., payment link title)

​
Source Types

SourceDescriptionUse Case
payment_linkPayment made through a Payment LinkTrack which products/campaigns drive revenue
apiPayment created directly via the APIIdentify programmatic payments
subscriptionPayment from a subscription renewalTrack recurring revenue

​
Why Use Source Tracking?

Source tracking helps you answer questions like:
  • “Which payment link generated the most revenue?”
  • “What percentage of this customer’s payments came from subscriptions vs. one-time purchases?”
  • “Which marketing campaign (payment link) converted this customer?”
When creating a payment link, give it a descriptive name that will appear in source_description: 
const link = await reevit.paymentLinks.create({
  name: 'Summer Sale - Premium Plan', // This appears in source_description
  amount: 9900,
  currency: 'GHS',
  // ...
});
When customers pay through this link, their payment history will show: 
{
  "source": "payment_link",
  "source_id": "pl_abc123",
  "source_description": "Summer Sale - Premium Plan"
}

​
🔗 The external_id Field

The external_id is critical for syncing Reevit with your internal systems.
  • What it is: A unique identifier from your database (e.g., usr_abc123).
  • Why use it: When a webhook fires, you can use the external_id to immediately look up the customer in your database without needing to map Reevit IDs.
  • Lookup: GET /v1/customers?external_id=usr_abc123
The external_id must be unique within your organization. An attempt to create a customer with a duplicate external_id will return an error.

​
✅ Best Practices

  1. Always Set external_id: Use your internal user ID to keep systems in sync.
  2. Use Tags for Segmentation: Apply tags like churned, active, trial to power analytics and workflows.
  3. Store Contact Info: Providing email and phone enables automated receipt sending and SMS notifications.

​
📚 Related Resources

Subscriptions

Create recurring billing plans linked to customers.

Payments

Link individual payments to customer profiles.

Workflows

Send automated emails based on customer events.

Webhooks

Get notified when customer data changes.