Skip to main content
POST
Create a customer

Authorizations

Authorization
string
header
required

Use a Bouclay secret key (sk_test_..., sk_live_...) or restricted key (rk_test_..., rk_live_...).

A secret key can call every endpoint. A restricted key can only call the endpoints its scopes cover. A scope is {resource}:{access}, for example customers:read or refunds:write, and write includes read. GET requests need read access and everything else needs write, except POST /subscriptions/{id}/items/{item}/preview, which only needs subscriptions:read. A request outside the key's scopes gets 403 permission_denied naming the missing scope, and its Idempotency-Key is not used up.

Publishable keys (pk_...) are rejected by server-side API endpoints. A key's mode scopes what it can see and charge: a test key can never reach a live card.

Headers

Idempotency-Key
string
required

Required for POST and PATCH requests. Replays identical method + path + body requests and rejects mismatched re-use.

Required string length: 1 - 255

Body

application/json
email
string<email>
required
name
string | null
phone
string | null
currency
string | null
Required string length: 3
Example:

"NGN"

externalRef
string | null
taxId
string | null

The customer's tax identification number (TIN), printed on their invoices.

Maximum string length: 32
Pattern: ^[A-Za-z0-9-]+$
billingEmails
string<email>[] | null

More addresses copied on the customer's invoices, receipts and credit notes, such as their finance team. Stored in lower case, each once. On update, the list replaces the one saved; [] or null clears it.

Maximum array length: 5
taxExempt
boolean

When true, no tax is charged on this customer's invoices.

customData
object | null

Response

Customer response.

data
object
required
meta
object
required