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

# Subscriptions

> Read recurring billing agreements, their dunning state and their payment history

## Overview

A subscription is created when a customer pays a `SUBSCRIPTION` payment link. Compago then charges the saved card on the agreed cadence. These endpoints let you read those agreements and their billing history.

<Info>
  Read-only in this version. Pausing, resuming, cancelling, re-pricing and retrying a failed charge are done from the dashboard. Compago's automatic dunning retries failing subscriptions on its own regardless.
</Info>

## The subscription object

```json theme={null}
{
  "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "status": "ACTIVE",
  "amount": 499,
  "currency": "MXN",
  "billingPeriod": "MONTHLY",
  "chargedPeriods": 3,
  "maxBillingCycles": 12,
  "failedAttempts": 0,
  "maxFailedAttempts": 3,
  "failedBillingCycles": 0,
  "maxFailedBillingCycles": 3,
  "nextBillingDate": "2026-04-04T00:00:00.000Z",
  "lastBillingDate": "2026-03-04T00:00:00.000Z",
  "startedAt": "2026-01-04T00:00:00.000Z",
  "cancelledAt": null,
  "endedAt": null,
  "paymentLinkId": "11111111-2222-3333-4444-555555555555",
  "paymentLink": { "id": "11111111-2222-3333-4444-555555555555", "title": "Plan Pro", "description": null },
  "customer": { "firstName": "Ana", "lastName": "Ramirez", "email": "ana@example.com", "phoneNumber": null },
  "card": { "lastFourDigits": "4242", "network": "VISA", "fundingSource": "CREDIT", "issuingBank": "BANORTE" }
}
```

`GET /developer/v1/subscription/{id}` adds `totalCollected`, the sum of every pending and confirmed payment on the subscription, and `daysActive`.

## Lifecycle

| Status | Meaning |
| - | - |
| `ACTIVE` | Billing normally |
| `FAILING` | The most recent charge failed. Compago will retry automatically |
| `PAUSED` | Billing suspended from the dashboard. No charges are attempted |
| `CANCELLED` | Ended. Terminal |
| `COMPLETED` | Reached `maxBillingCycles`. Terminal |

### The two failure counters

`failedAttempts` counts retries **within** the current cycle and resets when a charge succeeds. When it reaches `maxFailedAttempts`, that cycle is written off and `failedBillingCycles` goes up by one. When `failedBillingCycles` reaches `maxFailedBillingCycles`, the subscription is cancelled.

Watch `failedBillingCycles` if you want to warn a customer before you lose them: it is how close the agreement is to ending. `failedAttempts` is noise inside a single month.

## Billing history

<Note>
  These examples call the production host. While you build, replace `https://api-harmony.compago.com` with `https://demo-api-harmony.compago.com` and use a key from the Demo dashboard. See [Environments](/get-started/environments).
</Note>

```bash theme={null}
curl "https://api-harmony.compago.com/api/developer/v1/subscription/$ID/payment?limit=50" \
  -H "x-api-key: $COMPAGO_API_KEY"
```

Returns the same payment object as [`GET /developer/v1/payment`](/developer/payments), cursor-paginated.

## Finding subscriptions at risk

```javascript theme={null}
async function atRiskSubscriptions(apiKey) {
  const url = new URL('https://api-harmony.compago.com/api/developer/v1/subscription');
  url.searchParams.set('status', 'FAILING');
  url.searchParams.set('limit', '100');

  const res = await fetch(url, { headers: { 'x-api-key': apiKey } });
  if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);

  const { data } = await res.json();

  return data
    .map(subscription => ({
      id: subscription.id,
      email: subscription.customer?.email,
      card: subscription.card?.lastFourDigits,
      // How many more failed cycles before Compago cancels the agreement.
      cyclesLeft: subscription.maxFailedBillingCycles - subscription.failedBillingCycles
    }))
    .filter(subscription => subscription.cyclesLeft <= 1);
}
```

<Tip>
  A failing subscription is nearly always an expired or replaced card. Point the customer at their card on file rather than asking them to subscribe again, which would start a new agreement and lose the history of this one.
</Tip>

## Filters

| Parameter | Notes |
| - | - |
| `status` | Repeat for several |
| `billingPeriod` | `WEEKLY`, `MONTHLY`, `YEARLY` and the rest |
| `createdAtFrom`, `createdAtTo` | ISO-8601 bounds |