Skip to main content
The Customers API lets you look up customer records associated with checkout sessions. A customer record is automatically created or updated whenever a checkout session is completed with a customerEmail value — you do not need to create customers manually. Use this API to look up a buyer’s payment history, verify past purchases, or retrieve a customer ID for cross-referencing with your own user database.
The Customers resource uses page-based pagination (via page and limit query parameters), not the cursor-based pagination used by other resources such as Payment Links and Checkout Sessions.

​
The Customer object

​
id
string
Unique identifier for the customer, e.g. "cus_01HXYZ".
​
object
string
Always "customer".
​
email
string
The customer’s email address as provided in the checkout session.
​
metadata
object | null
Arbitrary key-value pairs attached to the customer record. null if no metadata has been set.
​
createdAt
string
ISO 8601 timestamp of when the customer record was first created.
​
updatedAt
string
ISO 8601 timestamp of the most recent update to the customer record.

​
GET /customers

Returns a page-based list of customer records for your account, ordered by creation time, most recent first. Required scope: customers:read

​
Query parameters

​
limit
integer
Number of results per page. Between 1 and 100. Defaults to 25.
​
page
integer
Page number to retrieve, starting at 1. Defaults to 1.
​
email
string
Filter results to the customer with this exact email address. Useful for looking up a specific buyer.

​
Example request — list all customers

curl "https://your-domain.com/api/v1/customers?limit=25&page=1" \
  -H "Authorization: Bearer ck_test_YOUR_KEY"

const result = await client.customers.list({ limit: 25, page: 1 });

​
Example request — look up by email

curl "https://your-domain.com/api/v1/[email protected]" \
  -H "Authorization: Bearer ck_test_YOUR_KEY"

const result = await client.customers.list({ email: "[email protected]" });

​
Example response 200

{
  "object": "list",
  "data": [
    {
      "id": "cus_01HXYZ",
      "object": "customer",
      "email": "[email protected]",
      "metadata": null,
      "createdAt": "2024-01-15T10:35:00.000Z",
      "updatedAt": "2024-01-15T10:35:00.000Z"
    }
  ],
  "total": 42,
  "page": 1,
  "limit": 25
}
The response envelope for customer lists includes:
​
object
string
Always "list".
​
data
Customer[]
Array of customer objects for the current page.
​
total
integer
The total number of customers matching your query, across all pages.
​
page
integer
The current page number.
​
limit
integer
The number of results per page as requested.

​
GET /customers/{id}

Retrieves a single customer by their ID. Required scope: customers:read

​
Path parameters

​
id
string
required
The ID of the customer to retrieve, e.g. "cus_01HXYZ".

​
Example request

curl https://your-domain.com/api/v1/customers/cus_01HXYZ \
  -H "Authorization: Bearer ck_test_YOUR_KEY"

const customer = await client.customers.retrieve("cus_01HXYZ");

​
Example response 200

{
  "id": "cus_01HXYZ",
  "object": "customer",
  "email": "[email protected]",
  "metadata": null,
  "createdAt": "2024-01-15T10:35:00.000Z",
  "updatedAt": "2024-01-15T10:35:00.000Z"
}
To find a customer by email rather than ID, use GET /[email protected]. The email filter performs an exact match, so it returns at most one result.