Endpoint responsible for updating, in a single request, the settings of several existing notifications for a customer.

Notifications define how and when Asaas will communicate events related to charges, such as creation, due date, receipt, or overdue status. These settings can determine the channels used, such as email, SMS, voice, or WhatsApp, and who will receive the communication, such as the paying customer or the provider.

This endpoint should be used when your integration needs to standardize or adjust multiple notifications for the same customer without making an individual call for each notification.

When to use

Use this endpoint when your integration needs to:

• configure default notifications after creating a customer;
• enable or disable several types of notification at once;
• change the communication channels used for different events;
• define whether certain notifications will be sent to the customer, the provider, or both;
• apply a single communication policy for customers registered by your platform;
• reduce the number of API calls when configuring notifications in batch.

This resource is especially useful in automated onboarding flows, in which the application creates a customer and then adjusts the notifications according to the platform’s business rule.

Recommended flow

In a typical integration, batch notification update follows the flow below:

Create or identify the customer
↓
Retrieve the customer's existing notifications
↓
Select which notifications need to be changed
↓
Build the payload with the customer and the list of notifications
↓
Send the batch update
↓
Validate the API response
↓
Persist or register the applied configuration, if necessary

The notifications must exist before the update. Therefore, before calling this endpoint, consult the customer’s notifications and use the identifiers returned by the API.

Main request parameters

This endpoint uses two main parameters in the request body:

The customer field must receive the customer identifier exactly as returned by the Asaas API, normally in the format cus_....

The notifications field must contain the notifications that will be changed. Each item in the list must represent an existing notification and must be related to the customer informed in the customer field.

Mandatory dependencies

Before using this endpoint, your integration must ensure that:

• the customer already exists in Asaas;
• the customer identifier has been stored by the application;
• the customer’s notifications have already been retrieved;
• the identifiers of the notifications to be changed are valid;
• the notifications sent belong to the informed customer;
• the request is authenticated with a valid API key.

This endpoint does not create new notifications. It only updates existing notifications.

Usage example

A common scenario is to standardize notifications right after creating a new customer.

{
  "customer": "cus_000005401844",
  "notifications": [
    {
      "id": "not_000000000001",
      "enabled": true,
      "emailEnabledForCustomer": true,
      "smsEnabledForCustomer": false,
      "phoneCallEnabledForCustomer": false,
      "whatsappEnabledForCustomer": false,
      "emailEnabledForProvider": true,
      "smsEnabledForProvider": false
    },
    {
      "id": "not_000000000002",
      "enabled": true,
      "emailEnabledForCustomer": true,
      "smsEnabledForCustomer": true,
      "phoneCallEnabledForCustomer": false,
      "whatsappEnabledForCustomer": false,
      "emailEnabledForProvider": false,
      "smsEnabledForProvider": false
    }
  ]
}

How batch update works

When receiving the request, Asaas uses the customer field to identify the customer and applies the changes to the notifications sent in the notifications list.

Each item in the list represents a notification that must be updated. The settings sent determine how that notification will be configured after processing.

Notifications that are not sent in the list should not be considered part of the requested update. If your integration needs to maintain a complete communication standard, send in the batch all notifications that need to be controlled by your business rule.

Important business rules

When using this endpoint, consider the following rules:

• the customer informed in customer must exist;
• each notification sent must already exist;
• the notifications sent must belong to the informed customer;
• the update is made on existing notification settings;
• the endpoint should not be used to create new notifications;
• the enabled channels depend on the data available in the customer’s registration and on the account permissions;
• voice notifications require the customer to have a registered phone number;
• notification settings can directly impact the communication sent to the payer;
• charge notifications may generate costs according to the fees applicable to the account.

Relevant behaviors

Some behaviors should be considered during implementation:

• changes to notifications start affecting the next communications generated for the customer;
• charges or communications already sent previously are not automatically recreated or resent;
• if a notification is disabled, new communications of that type will no longer be sent according to the applied configuration;
• if a channel is disabled for the customer, that channel will no longer be used for the respective notification;
• if a channel is enabled, validate whether the customer has the necessary data to receive the communication, such as email or phone;
• changes made in batch must be validated by the API response before being considered completed by the integration.

Precautions with batch updates

Because this is a batch update, it is recommended that the application treat the submission as a sensitive operation.

Before sending the request:

• avoid sending duplicate notifications in the same batch;
• validate whether all notification IDs belong to the informed customer;
• build the payload from the most recent consultation of the customer’s notifications;
• send only intentional changes;
• internally register which notification standard was applied;
• avoid changing notifications during critical flows without validating the impact on the end customer.

If an error occurs in the request, do not consider the configuration applied without first consulting the customer’s notifications again or repeating the update in a controlled way.

Common errors

Some common errors when using this endpoint include:

Always validate the API response and, in case of doubt, consult the customer’s notifications again to confirm the final state of the configuration.

Sandbox precautions

Batch notification update can be tested in Sandbox.

However, not all channels have the same behavior as the Production environment. In particular, WhatsApp notifications may not be available or may not be fully supported in Sandbox.

It is also important to avoid using real third-party data during tests, as channels such as email and SMS may send real communications depending on the tested scenario.

Best practices

For a safer and more predictable integration, it is recommended to:

• retrieve the customer’s notifications before updating them;
• store the customer ID returned by Asaas;
• apply notification standards right after creating the customer;
• validate the payload before sending it;
• keep logs of the applied settings;
• avoid real data in Sandbox tests;
• handle error responses before proceeding with charge creation;
• periodically review the notification settings used by the integration.

Operational impact

Notification settings directly affect communication with the end customer.

An incorrect configuration may cause:

• absence of charge notices;
• sending communications to undesired channels;
• charges for unplanned notifications;
• communication failures with customers without a registered email or phone;
• divergence between the communication rule expected by the platform and the one executed by Asaas.

Therefore, batch update should be used carefully in automated flows and, whenever possible, validated before creating charges in production.

Related content

See also:

• Changing a customer’s notifications;
• Retrieve a customer’s notifications;
• Update existing notification;
• Create new customer;
• Default notifications;
• What can be tested in Sandbox;
• Charges.