Skip to main content
POST
Error

Authorizations

Authorization
string
header
required

A merchant secret key (sk_…) sent as Authorization: Bearer <key>.

Headers

Idempotency-Key
string

A unique key that makes retries safe: the same key with the same request body returns the original response instead of repeating the operation.

Maximum string length: 255

Body

application/json
email
string
required

Customer email address. Must be unique per merchant and mode.

creation_source
string

Origin of the record (defaults to api when omitted).

first_name
string
last_name
string
phone
string
billing_address
object

Billing address. Can be added later.

shipping
object

Shipping details. Can be added later.

metadata
object

Up to 50 key/value pairs. Keys ≤ 40 chars, values ≤ 500 chars.

Response

The created customer.

id
string
required

Unique customer identifier (cus_…).

object
enum<string>
required
Available options:
customer
merchant_id
string
required
livemode
boolean
required

Whether this customer was created with a live (true) or test (false) key.

email
string
required
first_name
string
required

Empty string when not set.

last_name
string
required

Empty string when not set.

phone
string
required

Empty string when not set.

billing_address
object | null
required

Billing address; null when not set.

shipping
object | null
required

Shipping details; null when not set.

creation_source
enum<string>
required

How the customer was created (for example api).

Available options:
api,
checkout,
import,
dashboard,
platform
payment_settings
object
required

Payment configuration stored for the customer.

metadata
object
required
deleted
boolean
required

True when the customer has been soft-deleted.

created_at
integer
required

Unix epoch seconds.

updated_at
integer
required