Skip to main content
POST
Enroll 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.

Path Parameters

productID
string
required

Product ID.

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

"prod_1d4YogBuw00jAySh5mbUpk"

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

Enrollment created

An enrollment: this customer in this product. The id is the enrollment ID that subscriptions, invoices, usage and balances reference.

id
string<uuid>
required

Enrollment ID. This is the one billing and usage calls expect.

customerId
string
required

Customer ID. Do not use it for billing and usage calls; use id.

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

"cus_6Tq0Y2rGJ1aQ9zXk3LmPbV"

productId
string
required
Pattern: ^prod_[0-9A-Za-z]{22}$
Example:

"prod_1d4YogBuw00jAySh5mbUpk"

externalId
string
required

The customer's id in your own system.

metadata
object
required

The free-form data sent at enrollment.

creditAlertSent
boolean
required

Whether the low-balance alert has already been sent for this enrollment.

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

CPF or CNPJ.

pspRef
string | null

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