Skip to main content
POST
Create a customer

Authorizations

Authorization
string
header
required

Your account's secret key: Authorization: Bearer sk_test_… or sk_live_…. Server-side only.

Headers

Idempotency-Key
string

A unique key per operation (a UUID works). Retrying with the same key returns the original response.

Body

application/json
externalId
string
required

This customer's id in your own system (for example, your app's user id). Required; sending the same value again returns the same customer.

name
string | null

Customer name.

email
string<email> | null

Customer email.

phone
string | null
taxId
string | null

CPF or CNPJ.

country
string | null

The customer's country, as a two-letter ISO code (BR, US). Today sales are in Brazil; international sales are coming soon.

Example:

"BR"

pspRef
string | null

The customer's reference with the payment processor, if you already have one. Usually not needed.

metadata
object

Your own free-form JSON data. Stored on the enrollment.

Response

Customer created

The payer, at the level of your account. externalId is unique within the account.

id
string
required

Customer ID. Not the enrollment ID.

Pattern: ^cus_[0-9A-Za-z]{22}$
Example:

"cus_6Tq0Y2rGJ1aQ9zXk3LmPbV"

externalId
string
required

This customer's id in your own system.

stage
enum<string>
required
Available options:
lead,
converted
convertedAt
string<date-time> | null
required
conversionPaymentId
string | null
required
Pattern: ^pay_[0-9A-Za-z]{22}$
Example:

"pay_585vbbvnwDyuyeA3MTOitd"

createdAt
string<date-time>
required
name
string | null
email
string | null
taxId
string | null

CPF or CNPJ.

phone
string | null

Contact phone, in international format as digits only, without + (for example 5511999999999). Used for contact; it does not identify the customer.

pspRef
string | null

The customer's reference with the payment processor, when there is one.