Creating customers

Customer registration is the first step to create charges linked to a payer in Asaas.

When creating a customer, the API returns a unique identifier, such as cus_000005219613. This ID must be stored by your application and used in later operations, such as creating charges, subscriptions, queries, and registration updates.

When to use

Create a customer when your integration needs to register a payer to:

• create charges;
• create subscriptions;
• reuse registration data in future payments;
• query or update payer information;
• reconcile customers between your system and Asaas.

If the customer has already been created previously, reuse the ID saved in your application or query the registration before creating a new one.

Basic flow

Create or query customer
↓
Store the customer ID
↓
Create charge using the customer field
↓
Track the charge status

Create customer

POST /v3/customers
Check the complete reference for this endpoint

{
  "name": "Marcelo Almeida",
  "cpfCnpj": "24971563792",
  "mobilePhone": "4799376637"
}

Important fields

Some fields help with customer identification, communication, and reconciliation:

• name: customer name;
• cpfCnpj: customer CPF or CNPJ;
• email: e-mail used for communications;
• mobilePhone: customer mobile phone;
• externalReference: customer identifier in your system;
• notificationDisabled: defines whether the customer will receive notifications;
• additionalEmails: additional e-mails for notifications.

Check the endpoint reference to see all accepted fields, requirements, and expected formats.

Creation response

When creating a customer, the API returns an object with the registered data and the customer’s unique identifier.

Simplified example:

{
  "id": "cus_000005219613",
  "name": "Marcelo Almeida",
  "cpfCnpj": "24971563792"
}

The value returned in id must be sent in the customer field when creating charges for this customer.

Duplicate customers

You can query existing customers through the List Customers endpoint.

This validation is recommended in flows with:

• order reprocessing;
• asynchronous queues;
• automatic retry attempts;
• integrations that receive the same customer through more than one channel.

Best practices

• Store the customer ID returned by the API.
• Use externalReference to relate the customer to the registration in your system.
• Validate CPF/CNPJ, e-mail, and phone before sending the request.
• Avoid creating a new customer for each charge for the same payer.
• Before repeating a request with an error or timeout, check whether the customer has already been created.

API reference