Handle subscription blocks due to Split mismatch

A subscription can be blocked when the amount configured for the Payment Split exceeds the net value available in the charge.

During the block, new charges are no longer generated until the mismatch is fixed or the regularization period expires.

When the block occurs

Asaas checks Split compatibility when:

• a new subscription charge is created;
• a charge belonging to the subscription is processed;
• the available net value becomes lower than the amount allocated to the Split participants.

When the mismatch is identified:

• the subscription is blocked;
• the Split is temporarily disabled;
• new charges are no longer generated;
• the SUBSCRIPTION_SPLIT_DIVERGENCE_BLOCK event is sent.

How it works

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
    A["Detect Split mismatch"] --> B["Block the subscription"]
    B --> C["Send Webhook"]
    C --> D{"Fixed within 2 business days?"}

    D --> DSim(("Yes"))
    D --> DNao(("No"))

    DSim --> E["Unblock the subscription"]
    E --> F["Resume charges with Split"]

    DNao --> G["Expire the block"]
    G --> H["Disable the Split"]
    H --> I["Resume charges without Split"]

    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 analise fill:#FEE2E2,stroke:#DC2626,color:#7F1D1D,stroke-width:3px,font-size:17px

    classDef respostaSim fill:#22C55E,stroke:#15803D,color:#FFFFFF,stroke-width:3px,font-size:16px
    classDef respostaNao fill:#EF4444,stroke:#B91C1C,color:#FFFFFF,stroke-width:3px,font-size:16px

    class A inicio
    class D decisao
    class B,C,E,G,H validacao
    class F sucesso
    class I analise

    class DSim respostaSim
    class DNao respostaNao

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

1. Identify the block

Track subscription events via Webhook.

When a mismatch occurs, your application will receive:

SUBSCRIPTION_SPLIT_DIVERGENCE_BLOCK

Use subscription.id to identify the affected subscription.

The additionalInfo property contains additional information about the block.

See the Events for subscriptions.

2. Fix the mismatch

You can regularize it by adjusting:

• the subscription value; or
• the subscription Split configuration.

The adjustment must be made within 2 business days.

To update the subscription, use:

PUT /v3/subscriptions/{id}

When changing the Split, send the new configuration in split.

See the Update existing subscription endpoint.

If you need to fix the Split of an existing charge, update that charge separately.

See Split on subscriptions.

3. Wait for the unblock

When the mismatch is fixed within the deadline, Asaas automatically unblocks the subscription.

After the unblock:

• new charges are generated again;
• the Split remains configured;
• the updated values are used in the next charges.

Do not consider the flow back to normal just because you sent the update. Wait for confirmation of the subscription status via Webhook, or query the resource once when needed.

If the deadline expires

If the mismatch is not fixed within 2 business days:

• the block ends;
• the Split remains disabled;
• new charges are generated again without Split.

In this scenario, Asaas sends:

SUBSCRIPTION_SPLIT_DIVERGENCE_BLOCK_FINISHED

This event indicates that the block period has ended and the recurrence has resumed without the previous Split configuration.

How to handle the events

During this flow, focus mainly on:

Process the events idempotently using the Webhook id.

For the full payload and the other subscription events, see Events for subscriptions.

Next steps

• Configure and update Split on subscriptions
• Update the subscription
• Track subscription events
• Learn about Payment Split
• See the Subscriptions FAQ