Subscriptions

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.

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.

The subscription object

{
  "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

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.

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, cursor-paginated.

Finding subscriptions at risk

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);
}

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.

Filters

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

Get Started

Core Concepts

Developer API

Accept Payments

Integrations

Overview

The subscription object

Lifecycle

The two failure counters

Billing history

Finding subscriptions at risk

Filters

​Overview

​The subscription object

​Lifecycle

​The two failure counters

​Billing history

​Finding subscriptions at risk

​Filters

Overview

The subscription object

Lifecycle

The two failure counters

Billing history

Finding subscriptions at risk

Filters