Create customer

POST

/v1/customers

curl --request POST \
  --url http://localhost:8080/v1/customers \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "external_id": "example", "display_name": "example", "email": "example", "additional_emails": [ "example" ], "test_clock_id": "example" }'

• Local development

Authorizations

• BearerAuth

Parameters

Header Parameters

Idempotency-Key

string

Makes the call safe to retry. Send a unique value (a UUID works) and the same value on every retry. For 24 hours, a repeat with the same key, method, path and body gets the first response again, with an Idempotent-Replayed: true header, instead of running again. The error cases are in docs/api-surface.md. The usage routes do not take it: each usage event carries its own idempotency_key.

Request Body^required

Media typeapplication/json

object

external_id

required

string

display_name

required

string

email

string

additional_emails

Array<string>

<= 10 items

test_clock_id

Test mode only. Attaches the customer to a test clock.

string

Example ^generated

{
  "external_id": "example",
  "display_name": "example",
  "email": "example",
  "additional_emails": [
    "example"
  ],
  "test_clock_id": "example"
}

Responses

201

Customer created

Media typeapplication/json

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

Example

{
  "id": "hc_cus_42014438d82ddf33",
  "status": "active",
  "email_status": "unknown"
}

409

Customer already exists

422

A field failed validation, or the body has an unknown field (param names it; the body must use only the fields listed here). dunning_policy_id is not a create field: assign a policy with PATCH /v1/customers/{id}.

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"
  }
}