Customers API
Manage customers within your applications. Customers can be linked to licenses and external systems.
GET
/api/v1/apps/:slug/customers List all customers with optional filtering and pagination.
Query Parameters
| Parameter | Type | Description |
|---|---|---|
email | string | Filter by email (partial match) |
external_id | string | Filter by external ID (exact match) |
page | integer | Page number (default: 1) |
per_page | integer | Results per page (default: 20, max: 100) |
Example
$ curl "/api/v1/apps/my-app/customers?email=jane&page=1&per_page=20" \
-H "Authorization: Bearer sk_live_..."
{
"data": [...],
"meta": {
"total": 150,
"page": 1,
"per_page": 20
}
} POST
/api/v1/apps/:slug/customers Create a new customer.
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
email | string | Yes | Email address (unique per app) |
name | string | No | Customer name |
external_id | string | No | External system ID (e.g., Stripe) |
metadata | object | No | Custom JSON metadata |
POST
/api/v1/apps/:slug/customers/get-or-create Idempotent endpoint. Returns existing customer if email matches, otherwise creates new one.
GET
/api/v1/apps/:slug/customers/:id Get a single customer by ID.
GET
/api/v1/apps/:slug/customers/by-email Look up a customer by email address.
Example
$ curl "/api/v1/apps/my-app/customers/by-email?email=jane@example.com" \
-H "Authorization: Bearer sk_live_..." GET
/api/v1/apps/:slug/customers/by-external-id Look up a customer by external ID (e.g., Stripe customer ID).
PUT
/api/v1/apps/:slug/customers/:id Update customer information.
DELETE
/api/v1/apps/:slug/customers/:id Delete a customer. Cascades to all their licenses.
Warning: All licenses belonging to this customer will be permanently deleted.