Manage customers

Customers are created automatically when checkout succeeds with an email. The Customers page shows lifetime spend, payment count, and MRR contribution from active subscriptions.

Identifiers

Each customer has a public ID (cus_...). Emails are unique per merchant account within each mode (Sandbox vs Live).

List customers

Example request

GET /v1/customers?limit=50
Authorization: Bearer rk_live_...

Example response

{
  "object": "list",
  "livemode": true,
  "data": [
    {
      "id": "cus_01H...",
      "object": "customer",
      "email": "buyer@example.com",
      "name": "Ada Lovelace",
      "total_spent": 14900,
      "payment_count": 3,
      "created": 1722000000000,
      "livemode": true
    }
  ]
}

How to handle it

Use for CRM sync. Scope follows the API key mode. Max limit is 100.

Retrieve a customer

Example request

GET /v1/customers/cus_01H...
Authorization: Bearer rk_live_...

Example response

{
  "id": "cus_01H...",
  "object": "customer",
  "email": "buyer@example.com",
  "name": "Ada Lovelace",
  "total_spent": 14900,
  "payment_count": 3,
  "created": 1722000000000,
  "livemode": true
}

How to handle it

Map id to your user record. Prefer the customer.created webhook for first-time provisioning.

Webhook: customer.created

Example request

# Fired the first time an email becomes a customer in this mode

Example response

{
  "id": "evt_...",
  "type": "customer.created",
  "created": 1723000000,
  "data": {
    "id": "cus_01H...",
    "email": "buyer@example.com",
    "name": "Ada Lovelace",
    "currency": "usd",
    "merchant_id": "acct_...",
    "livemode": true
  }
}

How to handle it

Create the corresponding account in your app if it does not exist. Repeat checkouts with the same email update the existing customer.

Free trials

A customer email may complete only one free trial per mode. See Subscriptions.