> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fincle.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Subscriptions

> Recurring billing on credit card, with renewal managed by the platform.

A subscription is the recurring billing arrangement on credit card. The integrator starts the subscription once, and the platform makes the charges of the following cycles on the card provided, without a new request. The integrator neither schedules charges nor stores card data.

## Prerequisite

The amount and the billing interval of the subscription derive from a plan previously configured on the account. The plan is identified, in the request, by the `productId` and `offerSlug` fields. The interval may be weekly, monthly, bimonthly, quarterly, semiannual or annual.

## Starting the subscription

Starting a subscription comprises two operations. The first converts the card data into a token, through `POST /card-token`, as described in [Credit card](https://docs.fincle.com.br/guides/card.md). The second, `POST /subscriptions`, makes the first charge and creates the subscription.

```bash theme={null}
curl -X POST https://api.fincle.com.br/subscriptions \
  -H "Authorization: Bearer $FINCLE_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 4e7a9c12-6b38-4f05-8d21-9a3c5e7f1b64" \
  -d '{
    "productId": "cmdg7h2k1000c1yjn4d8w6r3s",
    "offerSlug": "monthly-plan",
    "description": "License agreement no. 4587",
    "postbackUrl": "https://api.example.com/webhooks/fincle",
    "card": { "cardToken": "tok_9f2c1a7b4d6e" },
    "customer": {
      "name": "Helena Martins Andrade",
      "email": "helena.andrade@example.com",
      "documentType": "cpf",
      "document": "31845792041"
    }
  }'
```

The request contains neither an amount nor a number of installments: the amount is that of the plan, and recurring charges are always made as a single payment.

```json theme={null}
{
  "success": true,
  "message": "Assinatura criada com sucesso",
  "data": {
    "transaction": {
      "id": "cmddiqpxo09zf1yju2kqkhgga",
      "status": "paid",
      "card": { "token": "tok_9f2c1a7b4d6e", "brand": "visa", "last4": "1111" },
      "fees": 995
    },
    "subscription": {
      "id": "cmdh1m4q2000e1yjn7f2z9t5v",
      "status": "active",
      "nextChargeAt": "2026-12-12T14:08:06.000Z"
    }
  }
}
```

| Field | Description |
| - | - |
| `transaction` | Transaction corresponding to the first charge, with the outcome of the authorization. |
| `subscription.id` | Subscription identifier. |
| `subscription.status` | Status of the subscription. |
| `subscription.nextChargeAt` | Time scheduled for the next charge. |

## First charge declined

The subscription is created only when the first charge is authorized. If it is declined, the response keeps status `200`, contains the transaction in the `refused` status, with the reason in `refuseReason`, and does not contain the `subscription` block. It is for the integrator to obtain another card and submit a new request.

A `400` response indicates that the plan was not found or is not configured as recurring. The temporary block of the payer described in [Credit card](https://docs.fincle.com.br/guides/card.md) applies to this operation.

## Statuses

| Status | Description |
| - | - |
| `active` | Subscription in force, with charges up to date. |
| `overdue` | Subscription with an unauthorized renewal charge, within the retry period. |
| `cancelled` | Subscription cancelled, by act of the integrator, the payer or the platform. |
| `completed` | Subscription ended upon reaching the number of charges set in the plan. |
| `failed` | Subscription ended by failure. |

## Renewal

At each cycle, the platform makes the charge on the card linked to the subscription. Each renewal charge is a transaction of its own and generates the ordinary transaction notifications, including `transaction_paid`, described in [Webhooks](https://docs.fincle.com.br/guides/webhooks.md).

## Renewal failure

A declined renewal charge moves the subscription to the `overdue` status, and the platform makes further charge attempts. Authorization of a further attempt restores the `active` status. Upon the fifth attempt without authorization, the subscription is cancelled by the platform.

## Cancellation

The `POST /subscriptions/{subscriptionId}/cancel` operation cancels the subscription. From cancellation onwards, no further charge is made.

```bash theme={null}
curl -X POST https://api.fincle.com.br/subscriptions/cmdh1m4q2000e1yjn7f2z9t5v/cancel \
  -H "Authorization: Bearer $FINCLE_TOKEN"
```

Cancellation does not return amounts already paid. The return of a specific charge depends on the [refund](https://docs.fincle.com.br/guides/refunds.md) of the corresponding transaction. The operation responds `400` when the subscription is already cancelled or completed.

## Retrieval

The `GET /subscriptions/{subscriptionId}` operation returns the subscription, with its status, the date of the next charge, the plan contracted and the identification of the payer. The `GET /subscriptions` operation lists the subscriptions of the account, filtered by plan (`productId`, `offerId`), status (`status`), period and search text, and paginated by the `page` and `limit` parameters.

The listing also contains consolidated indicators in the `stats` block.

| Field | Description |
| - | - |
| `activeSubscriptions` | Number of active subscriptions. |
| `monthlyRecurringRevenueInCents` | Monthly recurring revenue, in cents. |
| `lifetimeValueInCents` | Accumulated value, in cents. |
| `churnRate` | Cancellation rate. |
| `totalSubscriptions` | Total number of subscriptions. |
| `cancelledSubscriptions` | Total number of cancelled subscriptions. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.