Endpoint responsible for updating the registration information of an existing customer in Asaas using their unique identifier (id).

The update is used to keep data synchronized between the source system and Asaas, ensuring that future charges, notifications, and consultations use the customer’s most recent information.

When to use

Use this endpoint whenever your integration needs to update registration data of a customer already created in Asaas.

Some common scenarios include:

• change of name, email, phone, or mobile phone;
• address update;
• change of registered CPF or CNPJ;
• inclusion of additional emails for notifications;
• change of the customer identifier in the source system;
• update of the charge notification sending configuration;
• data synchronization between ERP, CRM, e-commerce, or proprietary platform and Asaas.

Before the update, it is necessary to know the customer identifier (id) in Asaas, normally obtained during creation or through customer consultation.

When not to use

Do not use this endpoint to:

• create a new customer;
• remove a customer;
• restore a removed customer;
• change charges already created;
• change subscriptions already created;
• change financial data of payments already issued;
• update specific customer notifications in batch;
• replace the customer creation flow.

If the customer does not yet exist in Asaas, use the customer creation endpoint.

If you need to change specific charge notifications, use the customer notification endpoints.

How the update works

The update modifies only the customer registration informed by the identifier sent in the request.

This endpoint does not create new customers or change charges, subscriptions, invoices, or other existing resources. However, the updated information may be used by operations performed after the registration change.

The update must be treated as a registration change of the existing customer, keeping the same id.

Missing, empty, or null fields

When assembling the update request, pay attention to how fields are handled:

Request parameter

This endpoint uses the customer identifier in the request path.

The id must correspond to an existing customer in the authenticated Asaas account.

Identifier example:

cus_000005401844

This identifier is returned when the customer is created and can also be obtained through customer listing or consultation.

Body parameters

The body fields must be sent according to the registration data that needs to be updated.

Parameters that deserve attention

Although all parameters are documented in the technical reference, some fields usually have greater impact during the integration:

• id — identifies which customer will be updated.
• cpfCnpj — must correctly represent the customer’s document.
• email — may be used in communications and notifications.
• phone and mobilePhone — may be used in communications and validations.
• postalCode, address, addressNumber, and province — impact the customer’s address registration.
• externalReference — facilitates synchronization between Asaas and the source system.
• notificationDisabled — defines whether the customer will continue receiving charge notifications.
• additionalEmails — adds extra recipients for charge notifications.
• foreignCustomer — must be informed for foreign customers when applicable.

Permission and authentication

To use this endpoint, the request must be authenticated with a valid API Key from the Asaas account.

The key used must belong to the same environment as the request:

• Sandbox API Key for Sandbox calls;
• Production API Key for Production calls.

If the API Key is missing, invalid, or belongs to another environment, the request may return an authorization error.

Request example

curl --request PUT \
  --url https://api-sandbox.asaas.com/v3/customers/cus_000005401844 \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'access_token: $ASAAS_API_KEY' \
  --data '{
    "name": "John Doe",
    "email": "[email protected]",
    "phone": "90999999999",
    "mobilePhone": "90999999999",
    "address": "Av. Paulista",
    "addressNumber": "150",
    "complement": "Suite 201",
    "province": "Downtown",
    "postalCode": "01310000",
    "externalReference": "12987382",
    "notificationDisabled": false,
    "additionalEmails": "[email protected],[email protected]",
    "observations": "great payer, no issues so far",
    "foreignCustomer": false
  }'

Response example

In case of success, the API returns the updated customer data.

{
  "object": "customer",
  "id": "cus_000005401844",
  "dateCreated": "2024-07-12",
  "name": "John Doe",
  "email": "[email protected]",
  "phone": "90999999999",
  "mobilePhone": "90999999999",
  "address": "Av. Paulista",
  "addressNumber": "150",
  "complement": "Suite 201",
  "province": "Downtown",
  "city": 12565,
  "cityName": "São Paulo",
  "state": "SP",
  "country": "Brazil",
  "postalCode": "01310000",
  "cpfCnpj": "24971563792",
  "personType": "FISICA",
  "deleted": false,
  "additionalEmails": "[email protected],[email protected]",
  "externalReference": "12987382",
  "notificationDisabled": false,
  "observations": "great payer, no issues so far",
  "foreignCustomer": false
}

Main response fields

Usage example

A common scenario occurs when a customer changes their registration data in an ERP, CRM, e-commerce, or proprietary platform.

After updating this information in the source system, the application can use this endpoint to keep the registration synchronized in Asaas as well, avoiding divergences between systems.

Flow example:

Customer updates the registration in the source system
↓
System identifies the change
↓
System retrieves the customer id in Asaas
↓
System sends the changed fields to Asaas
↓
Asaas updates the customer registration
↓
System registers the synchronization as completed

Precautions during synchronization

The update must always use the correct customer identifier.

It is also recommended to define a single source of truth for registration data, such as ERP, CRM, or another main system, reducing the risk of improper overwrites between integrations.

Important behaviors

After a successful update:

• the new information becomes part of the customer registration;
• future charges and notifications may use the updated data;
• the customer identifier (id) remains the same;
• the customer is not recreated;
• existing charges are not changed automatically;
• existing subscriptions are not changed automatically;
• resources linked to the customer remain associated with the same id.

If the informed customer does not exist or the identifier is invalid, the update will not be performed.

Important business rules

Before implementing this endpoint, consider the following rules:

• the customer must exist in Asaas;
• the informed id must belong to the authenticated account;
• the request must be authenticated with a valid API Key;
• at least one registration datum must be sent for update;
• sent data must respect the expected formats;
• additionalEmails must use emails separated by commas;
• notificationDisabled must be sent as a boolean;
• foreignCustomer must be sent as a boolean;
• fields sent with incorrect values may generate a validation error;
• the update does not create a new customer;
• the update does not remove the customer;
• the update does not automatically change charges, subscriptions, or other resources already issued.

Error handling

Before sending an update, it is recommended to internally validate whether the customer has already been synchronized with Asaas.

Some common errors during the integration include:

Whenever possible, handle these scenarios in the application to avoid inconsistencies between systems.

Operational impact

Since this endpoint directly changes the customer registration, it is recommended to use it only when there are effective changes to the registration information.

Unnecessary updates can:

• increase the volume of synchronizations;
• make change auditing difficult;
• overwrite data updated by another system;
• generate divergences between ERP, CRM, e-commerce, and Asaas;
• impact future notifications sent to the customer;
• affect future charges created after the update.

Therefore, keep control over the origin of the change and register when the synchronization was performed.

Best practices

For a safer implementation, it is recommended to:

• store the id returned when creating the customer;
• use externalReference to relate the customer to the source system;
• consult the customer before the update when there is doubt about the current data;
• send only the fields that need to be changed;
• avoid sending empty or null fields without prior validation;
• validate CPF, CNPJ, email, phone, and ZIP code before sending the update;
• maintain a single source of truth for registration data;
• register internal logs of the update;
• handle 400, 401, and 404 errors;
• test the flow in Sandbox before operating in Production.

Sandbox precautions

This endpoint can be tested in Sandbox.

During tests, it is recommended to validate:

• update of basic data, such as name, email, and phone;
• address update;
• update of externalReference;
• sending of additionalEmails;
• change of notificationDisabled;
• sending of empty or null fields, if this scenario exists in your integration;
• update attempt with nonexistent id;
• update attempt with API Key from the incorrect environment.

These tests help avoid improper overwrites and synchronization failures in Production.

Related content

This endpoint is usually part of the flow below:

Create customer
        ↓
Store the returned id
        ↓
Consult customer, when necessary
        ↓
Update customer
        ↓
Create charges, subscriptions, or other operations

If your integration still does not have the customer identifier, also see:

• Create customer;
• List customers;
• Retrieve customer by ID;
• Remove customer;
• Restore removed customer;
• Retrieve notifications of a customer;
• Update customer notifications.