Skip to navigation

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

  1. Send the email to Create customer (POST /api/customers) and save the response’s id.
  2. Pass that ID as customer_id when creating a checkout.
  3. 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.

  1. Create new records as customers. Replace POST /api/users with POST /api/customers and save the Customer’s id. Do not replace a User ID’s prefix: these are different objects.

  2. Find the customer for an existing User. If you already store a user_id, query the same account and environment:

    GET /api/customers/lookup?user_id=us_...

    lookup fills the path parameter; when user_id is supplied, that parameter is not used for the lookup.

  3. Save the customer’s ID. Use the response’s id. If there is no accessible customer, this endpoint returns 401; create the customer using their email with POST /api/customers.

  4. Use Customer in your checkouts. Send the saved customer_id to create and list checkouts. If you also send user_id, customer_id takes 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.