Endpoint responsible for removing a customer registered in the Asaas account.

This operation must be used carefully, as removing the customer impacts linked resources, such as subscriptions and charges that are still open.

When to use

Use this endpoint when your integration needs to remove a customer that should no longer remain active in the account registration.

Some common scenarios include:

• deletion of incorrect registrations;
• cleanup of test data;
• removal of duplicates;
• correction of customers created improperly;
• removal of a customer that will no longer be used in new flows;
• synchronization of a deletion performed in the source system.

When not to use

Do not use this endpoint to:

• update a customer’s registration data;
• correct name, email, phone, CPF/CNPJ, or address;
• cancel only a specific charge;
• cancel only a specific subscription;
• refund paid amounts;
• return money to the payer;
• remove charges already paid;
• replace an inactivation routine in the source system;
• delete your application’s internal financial history.

If the intention is to change customer data, use the customer update endpoint.

If the intention is to remove only one charge, use the charge removal endpoint.

If the intention is to end a recurrence, evaluate the subscription removal or update endpoint.

Request parameter

This endpoint uses only the customer identifier in the request path.

Identifier example:

cus_000005401844

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

This endpoint does not require sending parameters in the request body.

Authentication and authorization

To remove a customer, the request must be authenticated with a valid API Key from the Asaas account.

Before executing the operation, validate whether:

• the API Key belongs to the correct environment, Sandbox or Production;
• the API Key belongs to the account where the customer was created;
• the application has authorization to perform removal operations;
• the customer informed in the path belongs to the authenticated account;
• the identifier used corresponds to the correct customer.

Impact of removal

When removing a customer, the system also removes:

• linked subscriptions;
• charges awaiting payment;
• overdue charges.

This means that the operation can affect financial flows that were still open for this customer.

Precautions before deletion

Before removing a customer, validate whether there are linked resources that need to be maintained.

It is recommended to check:

• whether the customer has charges awaiting payment;
• whether the customer has overdue charges;
• whether the customer has active subscriptions;
• whether there are orders, sales, or contracts linked in the source system;
• whether the customer can still receive new charges through any automation;
• whether Webhooks or internal routines depend on the active customer;
• whether the removal must be reflected in external systems, such as ERP, CRM, or your own platform.

Recommended flow before removal:

Identify the customer in the source system
↓
Validate the customer id in Asaas
↓
Consult current customer data
↓
Check linked charges and subscriptions
↓
Confirm that the impacted resources can be removed
↓
Execute the removal
↓
Update the customer status in the source system

Request example

curl --request DELETE \
  --url https://api-sandbox.asaas.com/v3/customers/cus_000005401844 \
  --header 'accept: application/json' \
  --header 'access_token: $ASAAS_API_KEY'

Expected return

In case of success, the API returns 200 OK.

Successful return example:

{
  "deleted": true,
  "id": "cus_000005401844"
}

After receiving success in the removal, update the corresponding record in the source system to avoid new attempts to create charges, subscriptions, or synchronization for the removed customer.

Removal behavior

When using this endpoint, consider the following behaviors:

• the operation removes the customer from the account’s active flow;
• subscriptions linked to the customer are removed;
• charges awaiting payment linked to the customer are removed;
• overdue charges linked to the customer are removed;
• the operation does not create a new customer;
• the operation does not automatically change records in the source system;
• the operation does not represent a refund or return of amounts;
• repeated calls for a customer already removed may return an error;
• if the removal was improper, evaluate the removed customer restoration endpoint.

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 made with a valid API Key;
• the removal affects linked subscriptions;
• the removal affects charges awaiting payment;
• the removal affects overdue charges;
• the removal should not be used to correct registration data;
• the removal should not be used to return amounts from paid charges;
• the integration must prevent the creation of new charges for removed customers;
• the source system must be updated after removal.

Dependencies with other resources

The customer may be related to several integration resources.

Before removing, evaluate impacts on:

Operational impacts

Removing a customer can impact commercial, financial, and support routines.

Some important impacts:

• open charges may no longer be available;
• linked subscriptions may be removed;
• internal automations may fail if they try to use the removed customer;
• internal reports may show divergence if the source system is not updated;
• support teams may not locate the customer as active;
• external integrations may continue trying to synchronize data if they are not updated;
• incorrect removal may require later restoration, when applicable.

Therefore, internally register who requested the removal, when it occurred, and what the operational reason was.

Difference between removing, updating, and restoring a customer

Error handling

Some common errors when using this endpoint include:

Best practices

For a safer implementation, it is recommended to:

• store the customer id at the time of creation;
• consult the customer before removing it;
• check linked charges and subscriptions;
• block new internal charges before removing the customer;
• stop automations that may recreate charges for the customer;
• register operation logs in the source system;
• differentiate customer removal, charge removal, subscription cancellation, and refund;
• update the internal status after removal;
• avoid automatic retries without validating the customer’s current state;
• test the flow in Sandbox before using it in Production.

Sandbox precautions

In Sandbox, use this endpoint to validate the behavior of your integration before operating in Production.

During tests, it is recommended to validate:

• creation of a fictitious customer;
• creation of charges awaiting payment for this customer;
• creation of a subscription linked to the customer;
• removal of the customer;
• later consultation of the removed customer;
• behavior of the linked charges and subscriptions;
• removal attempt with invalid id;
• update of the source system after the 200 return;
• restoration of the removed customer, when applicable to the flow.

Related content

See also:

• Create new customer;
• List customers;
• Retrieve a single customer;
• Update existing customer;
• Restore removed customer;
• Create new charge;
• Delete charge;
• Create new subscription;
• Remove subscription;
• Webhooks for charges.