Create a subscription

Create a subscription so that Asaas generates recurring payments according to the configured frequency.

Each generated payment has its own ID, status, and financial cycle.

Before you start

Before creating the subscription:

• register the customer and store their ID;
• define the payment method;
• define the amount and frequency;
• choose the first due date.

If you use a credit card, see Creating a subscription with credit card.

How it works

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
    A["Register or look up the customer"] --> B["Define the recurrence"]
    B --> C["Create the subscription"]
    C --> D["Store the ID"]
    D --> E["Asaas generates the payments"]
    E --> F["Receive the Webhooks"]
    F --> G["Update the application"]

    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. Create the subscription

Send a request to:

POST /v3/subscriptions

Example:

{
  "customer": "cus_0T1mdomVMi39",
  "billingType": "BOLETO",
  "nextDueDate": "2027-01-15",
  "value": 19.90,
  "cycle": "MONTHLY",
  "description": "Pro Plan Subscription"
}

In this example:

• customer identifies the customer;
• billingType defines the payment method;
• nextDueDate defines the first due date;
• value defines the recurring amount;
• cycle defines the frequency.

The next payments will be generated automatically according to cycle.

See the endpoint Create new subscription.

2. Store the subscription ID

After creation, the API returns the subscription identifier.

Example:

sub_VXJBYgP2u0eO

Store this ID. It will be used to query, update, or delete the subscription and to retrieve its payments.

Expected result

The subscription will be created and ready to generate payments according to the configured recurrence.

Creating the subscription does not confirm any payment.

3. Track the subscription and payments via Webhook

Prefer Webhooks to keep your application in sync with Asaas.

Use subscription events to track changes in the subscription lifecycle, such as creation, update, deactivation, and deletion.

See the Events for subscriptions.

Use payment events to track the payments generated by the recurrence and their respective payments.

When a new payment is created, your application may receive:

PAYMENT_CREATED

The payment object has the subscription field, which identifies the originating subscription.

See the Events for payments.

4. Query the payments when necessary

To retrieve the payments already generated by the subscription, use:

GET /v3/subscriptions/{id}/payments

See the endpoint List payments of a subscription.

The listing returns only payments that have already been generated. Future payments not yet created do not appear in the result.

When updating a subscription

Changes made to the subscription affect the next payments by default.

To change a subscription, use:

PUT /v3/subscriptions/{id}

When you need to also apply supported changes to pending payments already generated, send:

{
  "updatePendingPayments": true
}

Payments already created are not changed by default.

See the endpoint Update existing subscription.

Next steps

• Track subscription events
• Track payment events
• List the payments of a subscription
• Update a subscription
• See the API Limits
• See the Subscriptions FAQ