Customers and migrating from User
Use Customer to identify the person you charge. A customer belongs to your merchant account: the same person can have a different Customer at each merchant. User is the shared identity Recurrente manages internally; you do not need to create it separately.
Create and use a customer
- Send the email to Create customer
(
POST /api/customers) and save the response’sid. - Pass that ID as
customer_idwhen creating a checkout. - To retrieve their checkouts, use
List checkouts
with
customer_id. You can combine it with date filters and pagination.
If Ana buys from your store and another merchant, save the ID returned by your
own account. The other merchant’s Customer does not identify Ana in your store.
For connected accounts, use the same X-ACCOUNT-ID when creating the customer,
creating the checkout, and listing their checkouts. Keep the API key environment
consistent too.
Migrate an integration that uses User
POST /api/users and existing user_id fields continue to work for compatibility.
-
Create new records as customers. Replace
POST /api/userswithPOST /api/customersand save the Customer’sid. Do not replace a User ID’s prefix: these are different objects. -
Find the customer for an existing User. If you already store a
user_id, query the same account and environment:lookupfills the path parameter; whenuser_idis supplied, that parameter is not used for the lookup. -
Save the customer’s ID. Use the response’s
id. If there is no accessible customer, this endpoint returns401; create the customer using their email withPOST /api/customers. -
Use Customer in your checkouts. Send the saved
customer_idto create and list checkouts. If you also senduser_id,customer_idtakes precedence.
The customer filter includes older checkouts that only stored their user, but not
checkouts from another account or environment. An unknown or inaccessible
customer_id returns 404; an empty or non-scalar value returns 400.
The User reference remains available by direct link for existing integrations.

