FAQ - Subscriptions

Subscriptions FAQ

Check the main behaviors of Subscriptions, from charge generation to changes, Webhooks, credit card, Split and ending the recurrence.

What is the difference between a subscription and an installment?

A subscription generates new charges over time according to the configured cycle.

In an installment, the installments belong to a single operation and are created as part of that installment plan.

Use Subscriptions for ongoing billing. Use installments when you need to split a single charge into installments.

Which payment methods are supported?

Subscriptions can use:

bank slip (boleto);
Pix;
credit card.

Payment behavior depends on the chosen method.

When are charges generated?

By default, each subscription charge is created 40 days before the due date.

This period can be configured in the account to:

14 days before;
7 days before.

Future charges are not all created when the subscription is created. They are generated gradually according to the recurrence.

See Subscriptions (recurrence).

Does payment happen automatically?

It depends on the payment method.

Payment method	Behavior
Bank slip (boleto)	Asaas generates the charge and the payer makes the payment
Pix	Asaas generates the charge and the payer makes the payment
Credit card	Asaas generates the charge and attempts the payment on the due date

Creating the subscription does not represent the confirmation of a payment.

Is the card charged when the subscription is created?

Usually, no.

When a subscription with credit card is created, the card is validated and used for future charges.

The first charge occurs on nextDueDate. If nextDueDate is the current date, the charge may be processed immediately.

See Creating a subscription with credit card.

Can I change a subscription?

Yes.

You can update settings such as amount, cycle, due date, payment method and status:

PUT /v3/subscriptions/{id}

By default, changes are applied to future charges.

To also apply supported changes to pending charges that have already been generated, send:

{
  "updatePendingPayments": true
}

See the Update existing subscription endpoint.

Can I change the credit card?

Yes.

Use the specific endpoint:

PUT /v3/subscriptions/{id}/creditCard

The operation does not make an immediate charge.

The new card starts being used by the subscription and also by the pending charges linked to it.

See the Update subscription credit card endpoint.

How do I track the subscription and its charges?

Use two groups of Webhooks:

Subscription events: track creation, update, deactivation, removal and Split-related behaviors;
Payment events: track each generated charge and its financial cycle.

When a subscription charge is created, the PAYMENT_CREATED event contains the subscription field, which lets you identify the originating recurrence.

See Subscription events.

See Payment events.

👍
Recommended
Use Webhooks as the main synchronization mechanism.
Avoid frequent polling to check whether a subscription or charge has changed status. GET requests consume the API quota and are also subject to concurrent request limits.
Use the query endpoints for one-off retrieval, validation or reconciliation. See API limits.

Can I list the charges of a subscription?

Yes.

Use:

GET /v3/subscriptions/{id}/payments

The endpoint returns only charges that have already been generated. Future charges do not appear in the list yet.

See the List payments of a subscription endpoint.

Can I issue invoices automatically?

Yes.

You can configure automatic issuance of NFS-e (service invoices) for subscription charges and define when each invoice should be issued.

See Issue invoices automatically for subscriptions.

Can I use Payment Split?

Yes.

The Split configured in the subscription works as a template for the new charges of the recurrence.

If the amount allocated to the Split exceeds the available net amount, the subscription may be blocked and stop generating new charges until the issue is resolved or the block ends.

See the Blocking flow due to Split divergence.

Can I pause a subscription temporarily?

Yes.

Update the status to:

INACTIVE

While inactive, the subscription does not generate new charges. Existing charges remain unchanged.

To reactivate it, change the status to ACTIVE and provide a new nextDueDate.

See the Update existing subscription endpoint.

What happens when a subscription is removed?

Removal permanently ends the recurrence:

DELETE /v3/subscriptions/{id}

New charges are no longer generated.

In addition, Asaas removes the pending or overdue charges that still belong to the subscription.

If you only intend to pause the recurrence temporarily, use status = INACTIVE instead of removing the subscription.

See the Remove subscription endpoint.

Next steps

Updated 2 days ago

Did this page help you?