Create a Checkout with recurring subscription

Create a credit card Checkout so that, after the payment journey is completed, Asaas creates a recurring subscription.

Use chargeTypes = RECURRENT and set the recurrence rules in subscription.

Before you start

Before creating the Checkout:

• define the subscription items and values;
• choose the recurrence frequency;
• define the date of the first charge;
• prepare the success, cancellation, and expiration URLs;
• configure the Webhooks for Checkout, subscriptions, and payments.

How it works

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
  A["Define the recurrence"] --> B["Create the Checkout"]
  B --> C["Store the ID"]
  C --> D["Make the link available"]
  D --> E["Payer completes the Checkout"]
  E --> F["Create the subscription"]
  F --> G["Generate recurring charges"]
  G --> H["Receive the Webhooks"]

  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,G validacao
  class H sucesso

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

1. Configure the recurrence

To create a subscription, use:

{
  "billingTypes": ["CREDIT_CARD"],
  "chargeTypes": ["RECURRENT"]
}

The subscription object is required when chargeTypes includes RECURRENT.

In it, define the recurrence rules:

{
  "subscription": {
    "cycle": "MONTHLY",
    "nextDueDate": "2027-01-31 15:02:38",
    "endDate": "2027-12-31 15:02:38"
  }
}

In this example:

• cycle = MONTHLY sets a monthly recurrence;
• nextDueDate sets the date of the first charge;
• endDate limits the subscription period.

2. Create the Checkout

Send a request to:

POST /v3/checkouts

Example:

{
  "billingTypes": ["CREDIT_CARD"],
  "chargeTypes": ["RECURRENT"],
  "minutesToExpire": 60,
  "callback": {
    "cancelUrl": "https://mysite.com/canceled",
    "expiredUrl": "https://mysite.com/expired",
    "successUrl": "https://mysite.com/success"
  },
  "items": [
    {
      "name": "Monthly plan",
      "description": "Monthly subscription",
      "quantity": 1,
      "value": 100.00
    }
  ],
  "subscription": {
    "cycle": "MONTHLY",
    "nextDueDate": "2027-01-31 15:02:38",
    "endDate": "2027-12-31 15:02:38"
  }
}

See the Create new checkout endpoint.

If your application already has the payer's data, see How to provide customer data.

3. Make the Checkout available

Creating the Checkout returns its ID.

Store this identifier and use it to build the URL that will be made available to the payer.

See Checkout link and customer redirection.

Expected result

After the payer completes the Checkout, Asaas creates the subscription with the recurrence defined in subscription.

The next charges are generated according to cycle and have their own lifecycle.

4. Track the Checkout and the subscription via Webhook

Use Webhooks according to the resource you want to track:

To confirm the Checkout completion, track CHECKOUT_PAID.

To record the created subscription, track SUBSCRIPTION_CREATED.

After that, track the recurring charges through the payment events. The payment object has the subscription field, which identifies the originating subscription.

• Events for Checkout
• Events for subscriptions
• Events for payments

Common errors

If the Checkout is not created, check:

• whether RECURRENT was provided in chargeTypes;
• whether the subscription object was sent;
• whether cycle, nextDueDate, and the other recurrence rules are valid;
• whether callback and items were filled in correctly;
• whether minutesToExpire is between 10 and 1440 minutes.

For other scenarios, see Common errors and best practices.

Next steps

• Set up the link and redirection
• Track the Events for Checkout
• Track the Events for subscriptions
• Track the Events for payments
• Set up Payment Split in Checkout
• See the Asaas Checkout FAQ