Subscriptions (add-on)

A page of subscriptions, each with its status, plan, customer, billing mode, payment provider, current period, next billing date and frozen amount. The response also carries a count per status, the full status vocabulary and the base currency. q matches an email address or a prefix of the subscription's own link hash, which are the two things a support conversation ever starts with. Filters this endpoint does not recognise are dropped rather than passed through, and per_page is capped at 200 with the figure actually used reported back.

One subscription in full: the row with its status, frozen amount, current period, next billing date, billing mode, provider and failed-attempt count; the plan behind it; every order it has produced, which are ordinary KahunaCart orders with numbers, receipts and invoices of their own; and the whole timeline. Read the timeline rather than reasoning from the status, because a status says where a subscription is and only the timeline says how it got there, which is what answers why a card was charged twice in March. Read this before acting on a subscription, since which actions are legal depends on the status it is in now.

The store's recurring-revenue figures right now: monthly and annual recurring revenue per currency, the counts of active, trialing, past-due and paused subscriptions, and how many plans exist. MRR is every live subscription's amount restated monthly, using 12 months, 52 weeks or 365 days to the year, computed in integer minor units with one rounding at the end. Only active and past_due count toward it, because both are money the store is contracted to receive; trials are reported separately since nothing has been contracted yet. Currencies are kept apart and never added together, with the store's own as the headline.

End a subscription, at the end of the period already paid for or immediately. at_period_end defaults to true and that default is the important half: a customer who cancels in week one of a month they have paid for keeps the month, and cancelling now throws that paid period away, so it has to be asked for by name. At period end is legal from active, trialing, past_due and paused, and a subscription that has already ended is refused with 422; cancelling now is legal from anything not already cancelled or expired, an abandoned incomplete checkout included. On a provider-mode subscription the platform is told first and the store's own row changes either way, so read mirror on the response: a state of failed means the agreement Stripe or Polar still holds will charge the customer again next month whatever this store says, and somebody has to finish the job at the provider. There is no undo for cancelling now; a scheduled cancellation is undone with uncancel_subscription.

Clear a cancellation scheduled for the end of the period, which is what a retention call ends in. Refused with 422 when nothing was scheduled, rather than quietly succeeding, because telling a customer they are still subscribed when nobody had cancelled makes them doubt every other message. Also refused on a subscription that has already ended. The store's record always changes, since this only restores something the store took away; the platform is asked to resume the agreement as well, and mirror on the response says whether it agreed, could not, or had nothing to be told.

Stop the calendar without ending the subscription. Nothing renews once it is paused and it can be resumed later. Legal only from active and trialing; anything else, a cancelled or expired subscription included, is refused with 422 before the payment platform is asked anything. This is the one action that does not go ahead locally when the platform will not have it: a pause the platform did not accept would stop access while the card went on being charged, so a mirror state of unsupported or failed leaves the row untouched and the subscription still running. Most platforms schedule a pause rather than applying it, because the customer has already paid for the period they are in — Polar and Stripe both do. Where the platform reports the agreement as still live, the response's subscription carries pause_at_period_end: true and pauses_at (the epoch it stops), the status stays active, and the subscription goes on billing until then; the status moves to paused when the platform's own event says billing has stopped. Call resume_subscription to undo either kind. Invoice-mode subscriptions have no platform to ask and pause immediately.

Start the calendar again on a paused subscription, returning it to active — or call off a pause that was scheduled and has not taken effect, which is the same call at the platform and leaves the subscription running as it was. Legal from paused, and from a live subscription carrying pause_at_period_end; anything else is refused with 422, and an expired subscription can never be resumed at all, because grace ran out and the customer has to subscribe again. Unlike pausing, this always goes ahead in the store's own record even where the platform did not confirm it, since it only ever restores something the store took away. Read mirror for whether the platform agreed.

Push the current period out by a number of days without billing for them, moving the next billing date with it. A negative number pulls the period in instead. Nothing is charged and no order is created, so this is the store giving something away: use it for an outage, a support case that dragged on, or a mistake being corrected. The note is required and is written into the event at the moment it happens, because it appears on the customer's own timeline and somebody will ask six months later who authorised it. Zero days, more than 3650 days in either direction, and a subscription that has already ended are each refused with 422. Nothing is mirrored to the payment platform, so on a provider-mode subscription the platform's own charge date does not move.

Write a free-text note onto a subscription's timeline. Changes nothing about the billing, the period or the status; it records something, in the one place both the merchant and the customer read. Trimmed and stored to 2000 characters, and an empty note is refused with 422.