Skip to main content
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.
1

Create a plan

A plan holds the amount and the cadence. Attach it to the products it prices.
2

Create a checkout that names the plan

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.
3

Send the shopper to checkout_url

They pay once, in the normal hosted checkout. That first payment is cycle 1.
4

Gale takes it from there

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. 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. 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.

​
Endpoints

Every endpoint is scoped to the merchant the key belongs to — another merchant’s subscription returns 404, never someone else’s data.

Subscription Plans

The amount and cadence a subscription bills on, and how to attach one to your products.

Subscription Webhooks

Every event a subscription emits, and the block each one adds.

Stripe Payment Elements

The Custom Payment Method path where Gale owns the subscription.

Stripe Checkout

Where Stripe orchestrates the charge and owns the subscription object.