Skip to main content
POST
Create customer

Authorizations

Authorization
string
header
required

Bearer token authentication used for standard API calls. Format: 'Bearer YOUR_API_KEY'

Body

application/json
reference_id
string

Your external identifier for this customer (strongly recommended). When provided, acts as an idempotency key — creating a customer with the same reference_id returns the existing one. Cannot start with "con_" (reserved prefix). Can be used interchangeably with customer_id in all API endpoints.

Maximum string length: 255
Example:

"usr_abc123"

name
string

Display name. Used as contact hint until the customer authenticates.

Maximum string length: 255
Example:

"Jane Smith"

email
string<email>

Email address. Used as contact hint and for checkout pre-population.

Example:

"jane@example.com"

phone
string

Phone number in E.164 format. Used as contact hint and for checkout pre-population.

Example:

"+14155552671"

metadata
object

Arbitrary key-value metadata (max 16KB serialized).

Example:

Response

Customer created

customer_id
string
required

Unique identifier for the customer

Example:

"con_test_01EXAMPLE00000000000000001"

reference_id
string | null
required

Merchant's external identifier for this customer. Used for idempotent creation — POST with the same reference_id returns the existing customer.

Example:

"usr_abc123"

contact
object
required
subscription
object | null
required

Active subscription summary, or null if none

metadata
object | null
required

Arbitrary key-value metadata stored on the customer. Set via PATCH.

Example:
created_at
string<date-time>
required

ISO 8601 timestamp when the customer was created

Example:

"2023-05-15T08:35:42Z"