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?

Benefit	Description
Unified History	See 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 Workflows	Use customer data in Workflows to send targeted emails.
Faster Checkout	Store 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

Field	Type	Description
`external_id`	string	Your internal identifier for this customer (e.g., your database user ID).
`email`	string	Customer’s email address. Used for receipts and workflow triggers.
`phone`	string	Customer’s phone number in E.164 format.
`name`	string	Full name or display name.
`tags`	string[]	Labels for segmentation (e.g., `["vip", "newsletter"]`).
`metadata`	object	Attach 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:

Field	Description
`source`	The origin type: `payment_link`, `api`, or `subscription`
`source_id`	The ID of the source (e.g., payment link ID, subscription ID)
`source_description`	Human-readable name (e.g., payment link title)

Source Types

Source	Description	Use Case
`payment_link`	Payment made through a Payment Link	Track which products/campaigns drive revenue
`api`	Payment created directly via the API	Identify programmatic payments
`subscription`	Payment from a subscription renewal	Track 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?”

Adding Metadata to Payment Links

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

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

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.

Get Started

Core Features

Developer Resources

Customers

Customers

🎯 Why Use Customer Profiles?

🛠️ Creating a Customer

Via SDK

Linking a Payment to a Customer

📋 Field Reference

📊 Customer Analytics

🔍 Payment Source Tracking

Source Types

Why Use Source Tracking?

Adding Metadata to Payment Links

🔗 The `external_id` Field

✅ Best Practices

Subscriptions

Payments

Workflows

Webhooks

​Customers

​🎯 Why Use Customer Profiles?

​🛠️ Creating a Customer

​Via SDK

​Linking a Payment to a Customer

​📋 Field Reference

​📊 Customer Analytics

​🔍 Payment Source Tracking

​Source Types

​Why Use Source Tracking?

​Adding Metadata to Payment Links

​🔗 The external_id Field

​✅ Best Practices

​📚 Related Resources

Subscriptions

Payments

Workflows

Webhooks

Customers

🎯 Why Use Customer Profiles?

🛠️ Creating a Customer

Via SDK

Linking a Payment to a Customer

📋 Field Reference

📊 Customer Analytics

🔍 Payment Source Tracking

Source Types

Why Use Source Tracking?

Adding Metadata to Payment Links

🔗 The `external_id` Field

✅ Best Practices

📚 Related Resources