Customers
The Customers API allows you to list and retrieve detailed information about your customers. You can filter, sort, and convert MRR to a base currency when listing customers.
List customers
Endpoint: GET /customers
Fetch a list of customers for your account, with optional filters and sorting.
Query parameters
| Parameter | Type | Description |
|---|---|---|
limit | integer | Maximum number of customers to return. |
status | string | Filter by customer status. Values: active, cancelled, all. Defaults to active. |
q | string | Search by customer name, email, or external ID (partial match). |
region | string | Space-separated region names or country codes. |
currency | string | Space-separated currency codes to filter customers. |
industry | string | Space-separated industries. |
channel | string | Space-separated channels. |
size | string | Space-separated customer sizes. |
selected-date | string | Date to filter by creation, trial, or conversion. Format: YYYY-MM-DD. |
selected-type | string | Type for date filter: lead, trials, or converted. Defaults to lead. |
interval | string | Interval for selected-date filter: day, week, month, quarter, year. Defaults to month. |
baseCurrency | string | Convert all MRR values to this currency. Defaults to the account's base currency. |
sort | string | Field to sort by: created_date, mrr, country, paid_started, cancel_date, trial_started, status. |
order | string | Sort order: asc or desc. Defaults to descending by MRR. |
Response
{
"result": {
"count": 2,
"list": [
{
"id": "cus_123",
"name": "Acme Inc",
"email": "[email protected]",
"created_date": "2024-01-15",
"country": "US",
"mrr": 5000,
"trial_started": "2024-01-10",
"paid_started": "2024-01-15",
"cancel_date": null,
"status": "active",
"currency": "usd"
}
]
}
}Get customer details
Endpoint: GET /customers/{customerId}
Retrieve full details for a single customer, including current subscriptions and MRR converted to a base currency.
Path parameters
| Parameter | Type | Description |
|---|---|---|
customerId | string | External ID of the customer. |
Query parameters
| Parameter | Type | Description |
|---|---|---|
baseCurrency | string | Convert MRR values to this currency. Defaults to account base currency. |
Response
{
"id": "cus_123",
"name": "Acme Inc",
"email": "[email protected]",
"created_date": "2024-01-15",
"country": "US",
"status": "active",
"currency": "usd",
"trial_started": "2024-01-10",
"paid_started": "2024-01-15",
"cancel_date": null,
"current_subscriptions": [
{
"plan_id": "plan_001",
"name": "Pro Plan",
"billing_freq": "month",
"billing_freq_count": 1,
"currency": "usd",
"mrr": 5000
}
],
"converted_mrr": 5000
}Notes
current_subscriptionscontains all subscriptions active for the customer.converted_mrrreflects MRR in the selectedbaseCurrency, calculated using the latest exchange rates.- Use filters and sorting to efficiently query large customer datasets.