Skip to navigation
API ReferenceCustomers

Create a customer

Creates a customer, usually at signup, keyed by your own ID in external_id. A customer is charged once it has a subscription.

Authentication

AuthorizationBearer

A secret key (rl_sk_test_..., rl_sk_live_...) or a restricted key with limited scopes (rl_rk_test_..., rl_rk_live_...). A restricted key can carry agent: true and an expires_at, and is what a coding agent should hold. Keys end in a checksum so secret scanners can recognize them. People create, roll and revoke keys in the dashboard; GET /v1/api_keys lists them, masked.

Request

This endpoint expects an object.
currencystringRequired
The customer's billing currency. Can't change later.
external_idstringOptional<=255 characters
Your own ID for the customer, such as an org ID. Unique per environment.
namestringOptional
emailstringOptionalformat: "email"
test_clockstringOptional

Sandbox only. Attach the customer to this test clock (clock_...).

payment_providerstringOptional

Always use this connected provider (by name) for this customer, ahead of the routing rules. While a customer names a provider, that provider can’t be removed. The removal returns 409 invalid_state with this customer in blocked_by.

metadatamap from strings to stringsOptional
Up to 50 keys of your own, with keys up to 40 characters and values up to 500 characters.

Response

The new customer.
idstring
object"customer"
currencystring
metadatamap from strings to strings
Up to 50 keys of your own, with keys up to 40 characters and values up to 500 characters.
livemodeboolean
created_atdatetime
external_idstringOptional
namestringOptional
emailstringOptionalformat: "email"
subscriptionstringOptional
The customer's current subscription, if any.
test_clockstringOptional
payment_providerstringOptional
The provider this customer pays through. Set by you as an override, or set when the customer first saves a payment method, after which the customer stays with that provider. Routing rule changes don't move them.
payment_method_statusenumOptional

Present once the customer has saved a payment method. unusable means the provider that holds it was removed: the method is kept on record, marked unusable and never charged, and the customer needs to save a new one. Left out before they save one.

Allowed values:

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
409
Conflict Error
422
Unprocessable Entity Error
429
Too Many Requests Error
500
Internal Server Error