Configure Split on subscriptions

Add split to the subscription to define how the amounts of recurring charges will be distributed among other Asaas accounts.

The configuration works as a template: each new charge generated by the subscription receives the Split defined in it.

Before you start

Have the walletId of each account that will receive part of the amount and define the transfer rule with fixedValue or percentualValue.

The calculation rules on netValue, limits and combinations are in Payment Split.

How it works

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
    A["Define the recipients"] --> B["Configure the Split"]
    B --> C["Create the subscription"]
    C --> D["Generate new charge"]
    D --> E["Apply the Split"]
    E --> F["Receive the charge"]
    F --> G["Settle the Split"]

    classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,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

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

    linkStyle default stroke:#94A3B8,stroke-width:2px

1. Configure the Split on the subscription

Include the split array when creating the subscription:

{
  "...": "...",
  "split": [
    {
      "walletId": "48548710-9baa-4ec1-a11f-9010193527c6",
      "fixedValue": 20.00
    },
    {
      "walletId": "0b763922-aa88-4cbe-a567-e3fe8511fa06",
      "percentualValue": 10.00
    }
  ]
}

See the Create new subscription endpoint.

Expected result

The subscription will be created with the Split configuration.

When a new charge is generated, it will receive the Split defined on the subscription.

2. Update the subscription's Split

To change the configuration, use:

PUT /v3/subscriptions/{id}

Send the new split:

{
  "split": [
    {
      "walletId": "48548710-9baa-4ec1-a11f-9010193527c6",
      "fixedValue": 10.00
    }
  ]
}

See the Update existing subscription endpoint.

The change is used by the next charges generated.

Charges that have already been generated do not have their Split updated automatically.

To change an existing charge:

1. list the charges already generated by the subscription;
2. identify the charge that needs to be changed;
3. update the split directly on that charge.

List the payments of a subscription.

See the Update existing payment endpoint.

3. Check the configured Split

To retrieve a specific subscription:

GET /v3/subscriptions/{id}

See the Retrieve a single subscription endpoint.

To query multiple subscriptions, use List subscriptions.

Track via Webhooks

Use subscription events to track changes in the recurrence configuration.

When you need to confirm the settlement of each Split of the generated charges, track:

PAYMENT_SPLIT_DONE

This event belongs to the charge lifecycle and is triggered individually for each settled Split.

• Subscription events
• Payment events

Split divergence

If the amount configured for the Split exceeds the available net amount, the subscription may be blocked and stop generating new charges.

In this scenario, handle the events:

SUBSCRIPTION_SPLIT_DIVERGENCE_BLOCK
SUBSCRIPTION_SPLIT_DIVERGENCE_BLOCK_FINISHED

See the subscription blocking flow due to Split divergence.

Next steps

• See the general Payment Split rules
• List the payments of a subscription
• Track Subscription events
• Track Payment events
• Handle blocks due to Split divergence
• See the Split FAQ