Creating a subscription

To create a subscription, simply call the subscription endpoint.

POST /v3/subscriptions
Check the complete reference of this endpoint

{
  "customer": "cus_0T1mdomVMi39",
  "billingType": "BOLETO",
  "nextDueDate": "2023-10-15",
  "value": 19.9,
  "cycle": "MONTHLY",
  "description": "Subscription Pro Plan",
}

The nextDueDate field defines when the first charge of the subscription will be made, which will follow the cycle as configured. The available cycles are:

WEEKLY - Weekly
BIWEEKLY - Biweekly (2 weeks)
MONTHLY - Monthly
QUARTERLY - Quarterly
SEMIANNUALLY - Semiannually
YEARLY - Annually

The subscription acts as a scheduler for creating charges. In the example above, a new bank slip type charge will be created monthly and sent to your customer, according to notification settings.

After creation, you will have the subscription ID, which follows a pattern similar to this: sub_VXJBYgP2u0eO.

Checking if a subscription has been paid

To know if a subscription has been paid, you should follow the webhook for payments. When a new charge is created for your subscription, you will receive a PAYMENT_CREATED event, and the subscription field will contain the ID of your subscription.

As soon as the charge related to the subscription, you will receive the PAYMENT_RECEIVED event in case of payment by bank slip, as in the example.

You can also check the charges created for a subscription through the endpoint:

GET /v3/subscriptions/{id}/payments
Check the complete reference of this endpoint

Editing a subscription

It is possible to change all the information of a subscription of type BOLETO or PIX.

POST /v3/subscriptions/{id}
See the complete reference of this endpoint.

When updating the subscription value or payment method, only future installments will be affected. To update the installments already created but not paid with the new payment method and/or new value, it is necessary to pass the parameter updatePendingPayments: true.

Retrieving subscription charges

Unlike an installment plan, where the ID of the first charge is returned upon creation, in the case of subscriptions, the charge is created after the subscription, and not together, so it is not possible to retrieve this ID at the time of creation.

To access the first charge created from the subscription, it is necessary to consume the API a second time at the endpoint:

GET /v3/subscriptions/{id}/payments
See the complete reference of this endpoint.

This endpoint will return all the charges already created in this subscription, as well as their statuses.