{
"customer_id": "cust_1a2b3c4d5e6f",
"email": "jane@example.com",
"metadata": {
"plan": "pro"
},
"created_at": "2026-01-24T12:00:00.000Z",
"updated_at": "2026-01-24T12:00:00.000Z",
"name": "Jane Doe",
"phone_number": "+2348012345678",
"billing_address": {
"line1": "40 Yaba Road",
"line2": null,
"city": "Lagos",
"state": "Lagos",
"postal_code": "101245",
"country": "NG"
}
}Customers
The customer object
A customer groups a buyer’s payments, subscriptions, and saved payment methods under one record.
billing_address is replaced, not merged, whenever you send an object for it in PATCH /v1/customers/{customer_id}. Any component you leave out of that object becomes null, even if a value was previously stored. This is the only field on the customer object where omitted, explicit null, and an object all mean something different. It is not guessable from the field list above, so read this before you write an update.| What you send | What happens |
|---|---|
billing_address omitted from the body | Untouched. The stored address, if any, is unaffected |
"billing_address": null | Cleared |
"billing_address": { ... } | Full replace. Every component not present in the object becomes null |
{
"line1": "40 Yaba Road",
"line2": "Suite 4",
"city": "Lagos",
"state": "Lagos",
"postal_code": "101245",
"country": "NG"
}
{"billing_address": {"city": "Paris"}} on PATCH /v1/customers/{customer_id}, intending to correct only the city, replaces the whole object instead:
{
"line1": null,
"line2": null,
"city": "Paris",
"state": null,
"postal_code": null,
"country": null
}
line1 and country are gone even though nobody meant to touch them, and the address is no longer valid to submit as evidence. Send the full object (all six keys, with the ones you want to keep repeated back) whenever you’re changing part of an address.
This is deliberate. A partial address written over a stored one produces a plausible-looking address that is actually wrong, and this value is what gets submitted as evidence on a dispute. A silent partial write is worse than a rejected request.
name and phone_number do not work this way. Sending either of those updates only that field and leaves the rest of the customer alone. billing_address is the exception.
Validation. country must be a real ISO-3166-1 alpha-2 code (for example NG, FR). Invalid codes are rejected. line1 and country are required whenever an address object is supplied. An all-empty object ({}) is rejected outright; send explicit null if your intent is to clear the address.Unique identifier for the customer, prefixed with cust_.
Example:
"cust_1a2b3c4d5e6f"
The customer's email address.
Example:
"jane@example.com"
Your own key-value data attached to the customer.
Example:
{ "plan": "pro" }
ISO 8601 timestamp when the customer was created.
Example:
"2026-01-24T12:00:00.000Z"
ISO 8601 timestamp when the customer was last updated.
Example:
"2026-01-24T12:00:00.000Z"
The customer's full name. null when not set.
Example:
"Jane Doe"
The customer's phone number in E.164 format, e.g. +2348012345678.
Example:
"+2348012345678"
The customer's billing address, or null if none is set.
Show child attributes
Show child attributes