List customers

GET

/v1/customers

curl --request GET \
  --url 'http://localhost:8080/v1/customers?dir=asc&limit=50&offset=0' \
  --header 'Authorization: Bearer <token>'

• Local development

Authorizations

• BearerAuth

Parameters

Query Parameters

status

string

external_id

string

Exact-match filter on the caller-assigned external ID.

ids

string

Comma-separated customer IDs to fetch exactly.

search

string

Case-insensitive substring match on display name, email, external ID, or ID. Matching runs post-decryption (PII columns are encrypted at rest), bounded to the first 5000 rows of the tenant’s filtered set; the rows and total stop there.

sort

string

One of display_name, email, external_id, status, created_at (default). A sort by display_name or email looks at 5,000 customers at most; the rows and total stop there.

dir

string

Allowed values: asc desc

limit

integer

default: 50 >= 1 <= 100

Rows per page, from 1 to 100. Default 50. Any other value, or one that is not a whole number, is a 422 with param: limit.

offset

integer

0

Rows to skip, 0 or more. Default 0. A negative value, or one that is not a whole number, is a 422 with param: offset.

Responses

200

Customer list

Media typeapplication/json

object

data

required

Array<object>

object

id

required

string

external_id

required

string

display_name

required

string

email

string

additional_emails

CC’d on billing documents and billing-state emails (invoice, receipt, dunning, payment failed, credit note) — never on credential-bearing emails (setup links, resets, invites). Normalized to lowercase bare addresses, deduped, capped at 10, never equal to the primary email. Stored encrypted at rest.

Array<string>

<= 10 items

status

required

string

Allowed values: active archived

created_at

required

string format: date-time

test_clock_id

Test clock this customer is pinned to (test mode only). When set, the customer — and any invoices/subscriptions created for it — run on the clock’s simulated time. Empty for live customers. The dashboard reads it to show the “test clock” badge + simulated-time banner on the customer and its invoices.

string

tenant_id

string

email_status

Deliverability of email, learned from bounce and complaint reports.

string

Allowed values: unknown ok bounced complained

email_last_bounced_at

string format: date-time

email_bounce_reason

string

dunning_policy_id

Assigned dunning policy; absent means the tenant default.

string

stripe_customer_id

The Stripe customer. Absent until the first payment-method action.

string

livemode

boolean

updated_at

required

string format: date-time

total

required

How many rows match the request’s filters, on every page, not only this one. The audit log and the customer list’s search and name or email sort say where they stop counting.

integer

Example

{
  "data": [
    {
      "id": "hc_cus_42014438d82ddf33",
      "status": "active",
      "email_status": "unknown"
    }
  ]
}

422

limit or offset is out of range or not a whole number, or the request sends the removed after cursor (param names it)

Media typeapplication/json

object

error

object

type

One of invalid_request_error, authentication_error, rate_limit_error or api_error. Every error the API answers has this shape, including an unknown path (404, code route_not_found) and a method the path does not take (405, code method_not_allowed, with an Allow header). The few exceptions are listed in docs/api-surface.md.

string

code

string

message

string

request_id

string

param

The request field the error is about. Sent only when the error names one. A request body may hold only the fields its operation lists, spelled and cased as listed: any other field, or one the server sets (such as id), is refused with 422 and param naming it. An operation with no request body lists no fields: send no body, {} or null. The Stripe and Postmark webhooks and the LiteLLM callback take their sender’s body as it comes.

string

Example

{
  "error": {
    "type": "invalid_request_error"
  }
}