Skip to main content
PATCH
Update 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

Path Parameters

customer
string
required

Body

application/json
email
string<email>
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
defaultPaymentMethod
string

One of the customer's cards, tokenized in this key's mode. A subscription with no card of its own charges the default. A card saved at checkout with setDefault is attached to the customer's automatic subscriptions as well, so it wins over the default there.

Example:

"pm_123"

Response

Customer response.

data
object
required
meta
object
required