Change a customer's notifications

Retrieve the notifications created for the customer and change only the settings your integration needs to control.

You can enable or disable a notification, choose the sending channels and, for compatible events, change when it is sent.

Before you start

Have the customer ID in the cus_... format.

Notifications are created automatically by Asaas when the customer is registered. To learn about the initial configuration, see Default notifications.

How it works

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
    A["Retrieve the notifications"] --> B["Identify the IDs"]
    B --> C{"How many will be changed?"}

    C --> CUma(("One"))
    C --> CVarias(("Several"))

    CUma --> D["Update the notification"]
    CVarias --> E["Update in batch"]

    D --> F["Validate the configuration"]
    E --> F

    classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:3px,font-size:17px
    classDef decisao fill:#FEF3C7,stroke:#D97706,color:#78350F,stroke-width:3px,font-size:17px
    classDef validacao fill:#E0F2FE,stroke:#0284C7,color:#0C4A6E,stroke-width:2px,font-size:17px
    classDef sucesso fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:3px,font-size:17px

    classDef respostaSim fill:#22C55E,stroke:#15803D,color:#FFFFFF,stroke-width:3px,font-size:16px
    classDef respostaOpcao fill:#8B5CF6,stroke:#6D28D9,color:#FFFFFF,stroke-width:3px,font-size:16px

    class A inicio
    class C decisao
    class B,D,E validacao
    class F sucesso

    class CUma respostaSim
    class CVarias respostaOpcao

    linkStyle default stroke:#94A3B8,stroke-width:2px
    linkStyle 2 stroke:#22C55E,stroke-width:4px
    linkStyle 3 stroke:#8B5CF6,stroke-width:4px

1. Retrieve the customer's notifications

Use:

GET /v3/customers/{id}/notifications

See the Retrieve notifications from a customer endpoint.

The response returns the existing notifications and the id of each configuration:

{
  "object": "list",
  "data": [
    {
      "id": "not_000042762597",
      "customer": "cus_000005358829",
      "enabled": true,
      "emailEnabledForProvider": true,
      "smsEnabledForProvider": false,
      "emailEnabledForCustomer": true,
      "smsEnabledForCustomer": true,
      "phoneCallEnabledForCustomer": false,
      "whatsappEnabledForCustomer": false,
      "event": "PAYMENT_RECEIVED",
      "scheduleOffset": 0
    }
  ]
}

Use the notification id, not the customer or charge ID, in the following steps.

A customer can have more than one notification for the same event. In these cases, also use scheduleOffset to identify the desired configuration.

2. Update a notification

To change only one configuration:

PUT /v3/notifications/{id}

Example to keep the notification active and send only email to the customer:

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

See the Update existing notification endpoint.

The main configuration fields are:

If enabled is false, the notification will not be sent, even if a channel remains enabled.

3. Change when it is sent

scheduleOffset is used in notifications related to the due date.

When updating a notification, use values compatible with the event:

In PAYMENT_DUEDATE_WARNING, the value represents days before the due date, or the due date itself when 0.

In PAYMENT_OVERDUE, it represents days after the due date.

Example of a notice 10 days before:

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

4. Update several notifications in one call

When you need to change several settings for the same customer, use:

PUT /v3/notifications/batch

Provide the customer and only the notifications that need to be changed:

{
  "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": false,
      "emailEnabledForCustomer": false,
      "smsEnabledForCustomer": false,
      "phoneCallEnabledForCustomer": false,
      "whatsappEnabledForCustomer": false,
      "emailEnabledForProvider": false,
      "smsEnabledForProvider": false
    }
  ]
}

Each id must represent an existing notification and belong to the customer provided in customer.

Notifications not sent in notifications are not part of the requested update.

See the Update existing notifications in batch endpoint.

Validate the configuration

After the update, query again:

GET /v3/customers/{id}/notifications

Confirm that enabled, the channels and scheduleOffset match the expected configuration.

Changes affect upcoming communications. Notifications already sent are not recreated or resent automatically.

Next steps

• See the Default notifications
• Retrieve a customer's notifications
• Update an existing notification
• Update notifications in batch
• Go back to the Notifications Introduction