> ## Documentation Index
> Fetch the complete documentation index at: https://docs.withgale.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Subscriptions
> How a Gale subscription is created, billed, retried, paused and cancelled.
A Gale subscription bills a saved card on a schedule you set, with the same HSA/FSA eligibility handling as a one-time payment. Gale is the biller: it authorises and captures each cycle, retries a failed card on a fixed schedule, and tells you what happened over webhooks.
## How one is created
There is no "create subscription" API, and that is deliberate: a renewal replays a stored card without the shopper present, and only a real customer-initiated payment can authorise storing it. So a subscription always begins with a completed checkout.
A [plan](/subscriptions/plans) holds the amount and the cadence. Attach it to the products it prices.
`POST /v2/checkout` with `metadata.mode: "subscription"` and a `plan_id` on each line item. The plan supplies the amount and cadence — sending `interval` or `interval_count` in the cart metadata is rejected.
They pay once, in the normal hosted checkout. That first payment is cycle 1.
The card is saved, the subscription starts, and `subscription.created` fires. Renewals need no further calls from you.
## The first cycle settles slightly later
Cycle 1 is **authorised** during checkout and **captured** a short time afterwards — a substantiation window that lets an eligibility question be resolved before money actually moves. Between the two, the money is reserved but not taken.
`subscription.renewed` fires when the cycle is **captured**, not when it is authorised, so receiving it always means money moved. That is true of cycle 1 and of every renewal, so you handle one event rather than two.
**A dual-purpose product waits longer.** If the cart needs a Letter of Medical Necessity, capture is held until the letter is issued rather than settling on the timer. The subscription exists and the cycle is recorded throughout; it simply is not captured yet.
## Renewals
Gale charges each cycle on schedule, captures it, records the cycle, and emits `subscription.renewed`. A cycle that is still owed blocks the next one rather than being skipped, so you never see cycle 3 billed while cycle 2 is unpaid.
Changing the amount or cadence affects **future cycles only** — there is no proration, and the period already paid for keeps its original end date.
## When a card fails
A declined renewal is classified, not blindly retried, and `subscription.payment_failed` carries a `disposition` so you can branch on a field rather than interpret a bank's decline code.
| `disposition` | What Gale does | `status` becomes |
| ----------------- | ---------------------------------------------------------------------------------------------------- | ----------------- |
| `retry` | Retries at **+2, +5 and +9 days**, then gives up | `past_due` |
| `action_required` | **No retries.** The card needs the shopper — expired, invalid, or 3DS. A 14-day grace window applies | `action_required` |
| `terminal` | Never retried — blocked, restricted or suspected fraud | `unpaid` |
For `action_required`, mint a **card-update link** with `POST /v2/subscriptions/{id}/card-update-link`. It is single-use, valid 24 hours, and the shopper enters the new card directly with the processor — the number never passes through your systems or Gale's. A successful update resumes billing.
## Statuses
`status` on a subscription is one of these. It is also what the `status` filter on `GET /v2/subscriptions` accepts.
| `status` | What it means | Billing |
| ----------------- | ---------------------------------------------- | ----------------------------------------------------- |
| `active` | Renewing normally | Charges on schedule |
| `past_due` | A renewal was declined and is being retried | Retries at +2, +5, +9 days |
| `action_required` | The card needs the shopper's attention | **No retries.** Send a card-update link; 14-day grace |
| `unpaid` | Retries exhausted, or the decline was terminal | Stopped. A card update revives it |
| `disputed` | A cardholder charged back a cycle | **Paused**, reversibly — see below |
| `canceled` | Ended | Stopped permanently; the saved card is retired |
A subscription in `disputed` cannot be changed with `PATCH`, and it clears itself only when the dispute is reversed.
## Cancelling
`POST /v2/subscriptions/{id}/cancel` with `{"mode": "period_end"}` leaves the subscription active and billable through the period the customer already paid for, then stops instead of renewing. `cancel_at_period_end` flips to `true` while `status` stays `active`, and `subscription.canceled` fires when it actually ends — not when you schedule it.
That is reversible: `POST /v2/subscriptions/{id}/resume` calls it off any time before the period ends. Design your cancel screen around this rather than around a point of no return.
Ending a subscription **mid-period** is a support request. It retires the saved card, which makes it irreversible — restarting means a new subscription and a new checkout.
## Chargebacks pause billing, reversibly
If a cardholder disputes a cycle, Gale stops billing that subscription and sets `status` to `disputed`. Charging a card whose holder is disputing the last charge tends to produce more disputes, so the hold is the safe default.
It is not the end of the subscription. If the dispute is reversed, the subscription returns to **exactly** the status it held before — including a mid-dunning state — and renewals continue on the original schedule. You do not have to call anything.
One event, `subscription.disputed`, covers the whole lifecycle; branch on `stage` and `billing_held`. See [subscription webhooks](/webhooks/subscriptions).
## Endpoints
| Method | Endpoint | Purpose |
| ------- | ----------------------------------------- | ---------------------------------------------------------------------------- |
| `POST` | `/v2/checkout` | Start a subscription (`metadata.mode: "subscription"` + line-item `plan_id`) |
| `GET` | `/v2/subscriptions` | List — paginated (`per_page`, `page`), filterable by `status` |
| `GET` | `/v2/subscriptions/{id}` | One subscription, with its most recent cycles |
| `GET` | `/v2/subscriptions/{id}/invoices` | Every cycle — paginated |
| `PATCH` | `/v2/subscriptions/{id}` | Change amount, cadence, or both — future cycles only |
| `POST` | `/v2/subscriptions/{id}/cancel` | Stop at period end |
| `POST` | `/v2/subscriptions/{id}/resume` | Call off a scheduled cancellation |
| `POST` | `/v2/subscriptions/{id}/card-update-link` | Mint a single-use card-update link |
Every endpoint is scoped to the merchant the key belongs to — another merchant's subscription returns `404`, never someone else's data.
## Related resources
The amount and cadence a subscription bills on, and how to attach one to your products.
Every event a subscription emits, and the block each one adds.
The Custom Payment Method path where Gale owns the subscription.
Where Stripe orchestrates the charge and owns the subscription object.