Subscriptions Guide

Check the subscriptions guide for more information.

Endpoint responsible for creating a new recurring subscription in Asaas.

A subscription works as a charge scheduler, automatically creating new charges according to the configured periodicity. This resource is indicated for monthly fees, plans, SaaS subscriptions, service contracts, and any other scenario in which there is recurring payment.

After the subscription is created, the charges will be generated automatically until the subscription is removed or reaches the defined limit.

When to use

Use this endpoint when your application needs to:

• create recurring charges automatically;
• charge customers at periodic intervals;
• manage product or service subscriptions;
• automate recurring billing;
• use bank slip, Pix, or credit card as the payment method.

Main request parameters

Some fields play a fundamental role in the subscription behavior:

• customer — identifier of the customer who will be charged.
• billingType — defines the payment method used in recurring charges.
• value — value of each subscription charge.
• nextDueDate — defines the due date of the first charge.
• cycle — determines the periodicity of the charges.
• endDate — deadline for generating new charges.
• maxPayments — maximum number of charges that can be created.
• externalReference — subscription identifier in the source system.
• split — configures the automatic division of amounts, when applicable.
• callback — configures the redirect after payment, when supported by the flow.

Important business rules

When creating a subscription:

• the first charge will be created using the date informed in nextDueDate;
• the next charges will be generated automatically according to the periodicity informed in cycle;
• the value of each charge will be defined by the value parameter;
• the subscription remains active until it is removed or reaches endDate or maxPayments, when informed;
• each created charge has its own lifecycle and can be monitored individually.

If you use credit card, card validation occurs during subscription creation, but the charge will only be performed on the due date of each recurring charge.

Trial period

If your application works with a trial period (for example, 7 free days), simply inform in nextDueDate the date on which the first charge should occur.

Example:

• subscription created today;
• nextDueDate configured for 7 days from now;
• first charge will be generated with due date on that date.

If the credit card is informed during subscription creation, it will be validated and stored for automatic use on the first due date.

Behavior when informing the card later

If the subscription is created without the credit card data and the payer later informs a valid card, the behavior will be different.

In this scenario, the amount of the pending charge will be processed immediately after the card is registered, regardless of the date originally informed in nextDueDate.

This behavior exists to allow the immediate regularization of the charge that was waiting for a valid payment method.

How the flow works

In a typical integration, subscription creation follows the following journey:

Create subscription
        ↓
Subscription created
        ↓
Generate charges automatically
        ↓
Customer makes the payment
        ↓
Webhook informs the result
        ↓
Application updates the status

Charges are generated automatically by the subscription and each one has its own financial lifecycle.

Best practices

Operational impacts

Subscription creation does not represent receipt of payment.

Each charge will be created automatically according to the periodicity configured in cycle and must be monitored individually through the API or Webhooks.

Subsequent changes to the subscription may affect only future charges or, when supported by the operation, also pending charges.

Next steps

After creating a subscription, the integration usually proceeds to:

• Retrieve a subscription.
• Update a subscription.
• List charges of a subscription.
• Configure Webhooks.
• Manage recurring charges.