Endpoint responsible for updating the settings of an existing notification for a customer.

Notifications are used by Asaas to notify you and/or the payer about events related to payments, such as creation, due date, receipt, overdue status, or payment updates. Each customer has its own set of notifications, which are automatically created by Asaas when the customer is registered.

Use this endpoint when your integration needs to update a specific notification for a customer by changing its delivery channels, enabling or disabling the notification, or adjusting when it should be sent.

When to use

Use this endpoint when your integration needs to:

• disable a specific notification for a customer;
• enable or disable delivery channels such as email, SMS, WhatsApp, or voice calls;
• configure whether the notification should be sent to the payer, the provider, or both;
• change when notifications are sent before or after the due date;
• standardize the communication behavior for customers created by your platform;
• update a customer's notification without modifying their other notifications.

This endpoint is intended for individual updates. If you need to update multiple notifications for the same customer at once, use the Batch update notifications endpoint.

Recommended flow

Before updating a notification, your integration should retrieve the customer's existing notifications to identify which one needs to be modified.

Create or identify the customer
↓
Retrieve the customer's notifications
↓
Locate the desired notification
↓
Store or use the notification ID
↓
Update the existing notification
↓
Validate the configured delivery channels and sending schedule

To retrieve a customer's notifications, use:

GET /v3/customers/{id}/notifications

After identifying the desired notification in the returned list, use the notification's id field to update it.

Updating a notification

PUT /v3/notifications/{id}

The id parameter represents the unique identifier of the notification to be updated.

This identifier is neither the customer ID nor the payment ID. It is returned when listing a customer's notifications and identifies a specific notification configuration.

Parameters that affect notification behavior

Although the technical reference lists all available fields, some parameters have a direct impact on how notifications are sent.

Difference between disabling a notification and disabling delivery channels

The enabled field controls the notification as a whole.

When enabled is set to false, the notification will no longer be sent, even if one or more delivery channels remain enabled.

Delivery channel fields such as emailEnabledForCustomer, smsEnabledForCustomer, and whatsappEnabledForCustomer only control how the notification is delivered.

Example:

{
  "enabled": true,
  "emailEnabledForProvider": false,
  "smsEnabledForProvider": false,
  "emailEnabledForCustomer": true,
  "smsEnabledForCustomer": false,
  "phoneCallEnabledForCustomer": false,
  "whatsappEnabledForCustomer": false
}

In this example, the notification remains enabled, but it will only be sent to the payer by email.

Using scheduleOffset

The scheduleOffset field defines how many days before or after the payment due date the notification will be sent.

This field is mainly used for due date reminder and overdue payment notifications.

For the PAYMENT_DUEDATE_WARNING event, the accepted values are:

0, 5, 10, 15, 30

For the PAYMENT_OVERDUE event, the accepted values are:

1, 7, 15, 30

Update example

The example below keeps the notification enabled while sending it only by email to the payer.

{
  "enabled": true,
  "emailEnabledForProvider": false,
  "smsEnabledForProvider": false,
  "emailEnabledForCustomer": true,
  "smsEnabledForCustomer": false,
  "phoneCallEnabledForCustomer": false,
  "whatsappEnabledForCustomer": false
}

This configuration can be used when the platform wants to avoid sending notifications through multiple channels and keep communication limited to email.

WhatsApp and voice call notifications

Notifications to the payer can be sent through WhatsApp or automated voice calls, provided that the customer's registration data supports these channels.

To enable voice call notifications, the customer must have a landline or mobile phone number registered.

{
  "enabled": true,
  "phoneCallEnabledForCustomer": true
}

To enable WhatsApp notifications:

{
  "enabled": true,
  "whatsappEnabledForCustomer": true
}

Common use cases

Send notifications only to the payer

Use this configuration when your platform should not receive copies of notifications sent to the end customer.

{
  "enabled": true,
  "emailEnabledForProvider": false,
  "smsEnabledForProvider": false,
  "emailEnabledForCustomer": true,
  "smsEnabledForCustomer": true,
  "phoneCallEnabledForCustomer": false,
  "whatsappEnabledForCustomer": false
}

Disable a specific notification

Use this configuration when a particular type of communication should not be sent.

{
  "enabled": false
}

Send a reminder before the due date

Use this configuration for notifications of the PAYMENT_DUEDATE_WARNING type.

{
  "enabled": true,
  "emailEnabledForCustomer": true,
  "smsEnabledForCustomer": true,
  "scheduleOffset": 10
}

In this example, the notification will be sent 10 days before the due date, provided that the notification event supports this schedule.

Important considerations

• Retrieve the customer's notifications before attempting to update one.
• Always use the notification id, not the customer ID or payment ID.
• Validate the notification event before changing the scheduleOffset.
• Avoid enabling too many delivery channels unless necessary, as this may result in excessive communication with the payer.
• Consider any applicable notification fees before enabling SMS, WhatsApp, or voice call notifications.
• For bulk changes, prefer using the batch notification update endpoint.
• To disable all notifications when creating a customer, use the notificationDisabled attribute in the customer creation request.

Common mistakes

Using the customer ID instead of the notification ID

This endpoint expects the notification identifier in the path.

PUT /v3/notifications/{id}

The value provided in {id} must be obtained from the customer's notification list.

Setting an invalid scheduleOffset value

Each event accepts a specific set of scheduleOffset values. If an invalid value is provided for the notification type, the API will return a validation error.

Disabling delivery channels without disabling the notification

If enabled remains true, the notification will continue to be active. If all intended delivery channels are disabled, verify whether the notification should remain enabled or be completely disabled.

Related content

• Notifications overview
• Default notifications
• Retrieve customer notifications
• Batch update notifications
• Create new customer
• Disable notifications when creating a customer