Customers

Customers are the foundation of billing operations in RevKeen. Every subscription, invoice, and payment is associated with a customer. Each customer can have multiple payment methods, addresses, subscriptions, and orders associated with them.

What is a Customer?

A Customer record stores:

• Contact information -- Name, email, phone
• Payment methods -- Cards, bank accounts for future charges. Sending Direct Debit mandate from the customer record authorises a mandate only — it does not collect. See Start from a customer.
• Addresses -- Billing and shipping addresses
• Billing history -- All invoices, orders, and subscriptions
• Custom fields -- Additional data you define

Customer Fields

Reading the customer overview

Customer financial summaries show Unavailable when a reliable amount and its currency are not available. The customer's preferred currency does not establish the currency of historical totals. Open the individual records to inspect their amounts and currencies.

Invoices loaded counts the invoice records currently retrieved, which may be fewer than the customer's full history. A failed related-record request shows an error instead of an empty history. Duplicate comparison remains available when a financial summary cannot be shown.

Field names are snake_case, and an unknown field is rejected with 400 naming it in param. The camelCase spellings externalId, companyName, addressLine1, addressLine2, postalCode and customFields are still accepted for now: a request that uses one gets a Deprecation header and a Link to this page. Move to the snake_case names.

See Create a customer for the full schema.

Creating Customers

Changing an email address

Each customer email must be unique within your business. If another customer already uses the address, the edit form explains the conflict and keeps your entered details available. The change is not saved. Use a different email or open the existing customer record before continuing with an invoice or mandate.

Automatic Creation

Customers are automatically created when:

• A new email completes checkout
• You create an invoice for a new email
• Imported from integrations such as PracticeHub (Wodify is coming soon)

Via Dashboard

1. Navigate to Customer
2. Click + New Customer
3. Enter email and other details
4. Save the customer

Via API

import { RevKeenClient } from "@revkeen/sdk";

const client = new RevKeenClient({ apiKey: process.env.REVKEEN_API_KEY! });

const { data: customer } = await client.customers.create({
  email: "john@example.co.uk",
  name: "John Smith",
  phone: "+447700900123",

  // Optional: billing address
  company_name: "Smith Physio Ltd",
  address_line1: "10 High Street",
  city: "Manchester",
  postal_code: "M1 1AA",
  country: "GB",

  // Optional: custom metadata
  metadata: {
    salesRep: "jane@company.co.uk",
    tier: "enterprise",
  },
});

console.log(customer.id);

If another customer already uses the email address, or another customer whose external id you set through the API already has the same external_id, the API answers 409 with the conflicting field named in param (email or external_id) and nothing is created.

Listing Customers

// List customers, 20 at a time
const { data: customers, pagination } = await client.customers.list({
  limit: 20,
  offset: 0,
});

// Search by name or email
const { data: matches } = await client.customers.list({
  search: "john@example.co.uk",
});

search matches a customer's name or email as plain text, so % and _ in the term are matched as themselves.

To find the customer that holds your own identifier, filter by it: GET /v2/customers?external_id=usr_123 returns the customers whose external id equals it, or an empty list. It can return more than one only if an integration-synced customer carries the same value.

To walk every page, see Pagination.

Updating Customers

await client.customers.update("11111111-1111-4111-8111-111111111111", {
  name: "John Smith",
  metadata: {
    plan: "pro",
    upgraded_at: new Date().toISOString(),
  },
});

metadata is merged into the customer's existing metadata: keys you send are set, keys you leave out are kept, and a key set to null is removed. A customer synced from an integration keeps that integration's external_id; changing it through the API is refused.

Deleting Customers

Customers cannot be deleted through the public API. To remove a customer, contact RevKeen support.

Business Customers (B2B)

For B2B billing, you can associate customers with a business entity:

• Business name -- Legal entity name
• Tax ID -- VAT number, EIN, etc.
• Business address -- Separate from individual address

Enable business checkout in your checkout link settings to collect business information during purchase.

Payment Methods

Customers can have multiple saved payment methods:

Payment methods are securely tokenized by your payment gateway. RevKeen never stores raw card numbers.

Default Payment Method

One payment method can be marked as default. This is automatically used for:

• Subscription renewals
• Auto-pay invoices
• Retry attempts during dunning

Saved Card Security at Checkout

When a customer returns to checkout and has saved cards, they must verify their identity before accessing them. This is done via a 6-digit email verification code (or automatically if they have a trusted device cookie from a previous verification). Additionally, customers must re-enter their card's CVV for every saved card payment. See the Checkout page for details.

Addresses

Customers can have multiple addresses with different types:

Custom Fields

Extend customer data with custom fields defined in Settings > Custom Fields:

• Text fields (IDs, notes)
• Numbers (account numbers, scores)
• Dates (birthdays, contract dates)
• Dropdowns (status, category)
• Checkboxes (preferences, consent)

Health Scores and Intelligence

RevKeen automatically calculates a health score (0--100) for each customer and uses AI to predict payment failures and churn risk. See Customer Health Scores for details.

Customer Portal

Customers can self-manage their account through the Customer Portal:

• View and pay invoices
• Download invoice PDFs
• Update payment methods
• Manage subscriptions (pause, cancel)
• View billing history

The Customer Portal is available at pay.revkeen.com/portal/[your-slug].

You can also create a portal session programmatically to let customers manage their own billing:

const { data: session } = await client.customer.portalSessionsCreate({
  customer_id: "11111111-1111-4111-8111-111111111111",
  ttl_minutes: 30, // optional
});

// Redirect the customer to the portal
return redirect(session.url);

See Create a portal session.

Customer Events

There are no public webhook events for payment methods being added or removed. List a customer's saved methods with client.customers.paymentMethodsList.

Related

• Subscriptions -- Create subscriptions for customers
• Invoices and Orders -- Send invoices to customers
• Customer Portal -- Self-service portal for customers
• Dunning -- Automated payment recovery that feeds into health scores

Owner: david · Reviewed 1 Oct 2026 · Next review 31 Oct 2026