API Reference
Customers Endpoint
List, create, and update customer records via the API.
List customers
GET /customersScopes required: customers:read
Query parameters:
| Parameter | Type | Description |
|---|---|---|
email | string | Filter by email address |
externalId | string | Filter by your system's customer ID |
limit | number | Results per page (default: 20, max: 100) |
cursor | string | Pagination cursor |
Response:
{
"customers": [
{
"id": "cus_01abc...",
"email": "jane@example.com",
"name": "Jane Smith",
"externalId": "usr_12345",
"metadata": {
"plan": "pro"
},
"ticketCount": 3,
"createdAt": "2025-01-01T00:00:00Z"
}
],
"nextCursor": null
}Create a customer
POST /customersScopes required: customers:write
Request body:
{
"email": "john@example.com",
"name": "John Doe",
"externalId": "usr_99999",
"metadata": {
"plan": "enterprise",
"accountAge": "24 months"
}
}externalId is your internal ID for this customer. If you provide an externalId that already exists, the existing customer is returned (upsert behaviour).
Get a customer
GET /customers/:idScopes required: customers:read
Update a customer
PATCH /customers/:idScopes required: customers:write
Request body (all fields optional):
{
"name": "Jane Doe",
"metadata": {
"plan": "pro"
}
}metadata is a free-form key-value object (string values only). It's merged with existing metadata — to remove a key, set it to null.