Read a subscription
Requires billing:read. One subscription, its lines, and what may be done to it.
capabilities is why this is worth reading before rendering buttons: a scheduled plan change, proration and cancel-at-period-end are all things a gateway may not be able to do, and an interface that offers one anyway sends somebody into a refusal. It is absent — not full of false — when this server has no adapter for the gateway, because that is a fact about the deployment rather than about the provider.
Authorizations
A staff session token, uk_st_…. Minted by sign-up, sign-in or the two-factor exchange.
Headers
The organization the caller is acting on — the org_… code that appears in the panel URL. It identifies; the membership JOIN is what authorizes, so a forged code reads nothing. Absent, the session's default organization answers.
Path Parameters
The subscription's id here, not the gateway's id for it.
Query Parameters
Which environment to act in. A view parameter, valid only on the staff surface — a machine credential never chooses its environment, it is resolved from the key.
live, test Response
The subscription, with its lines and the gateway's capabilities.
What one of your customers is paying, mirrored from the gateway.
That word decides how to read every field below. The gateway is the source of truth about money; this is a local copy kept so an entitlement can be answered without a network call, joined to the rest of your data, and read while the gateway is unreachable. provider_synced_at is when the copy was last confirmed — null means never, which is what a checkout that was started and not completed looks like.
Who is billed. A subscription always hangs off a customer, including when that customer is a team of one.
What they are subscribed to, as opposed to how it is billed — which is items. Entitlements are computed from the plan's features, so this always has exactly one answer.
In our vocabulary, never a gateway's spelling, so this does not change when you change gateway.
incomplete is created and not yet paid — no access. past_due is paid before and a payment has failed; whether that keeps access is a grace-period decision and not this field's. unknown means the adapter did not recognise what the gateway said: it is a reason to look, never a reason to charge anybody or to cut them off, and it deliberately does not read as active or as canceled.
incomplete, trialing, active, past_due, paused, canceled, unknown The period paid for. Null together with the end, never one alone: an incomplete subscription has no period, and a made-up one is a date an entitlement expires on that nothing happens at.
A cancellation that has been scheduled and has not happened. The subscription is still active until current_period_end, which is why this is its own field rather than a status.
When it actually stopped. Null while it has not.
Null when there is no trial — which is a different fact from a trial that ended, and only one of them should make a screen say a trial expired.
Which gateway holds this subscription. Exactly one: that is who is charging the card.
stripe The merchant account, as the gateway names it. Empty until a health check has asked who the keys belong to.
The gateway's own id. Empty for a checkout that was started and never completed — a row that exists here and nowhere else, and the one state in which no act on this subscription is possible.
When this copy was last re-read from the gateway, as opposed to when the row was last written. Null means never confirmed. A mirror that cannot say how stale it is would be claiming to be the source.
The lines. Present on a single subscription, absent from the list.
What a gateway can do beyond the minimum every gateway can do. Every flag defaults to false, so a provider that declares nothing is treated as the weakest one — silence is never a claim. Read it to stop offering an act that would be refused.
Every flag below is always present. The object is emitted whole or not at all: absent means this server has no adapter loaded for the gateway, and it never means "some flags were left out". A reader must therefore distinguish false from missing rather than testing for falsiness — a key that is not here is not a gateway that cannot do something, it is a question nobody asked.
Present only on the answer to an act. true means the gateway was re-read afterwards and everything above is what it said. false means the act happened and the copy above is not (or not entirely) the gateway's answer — either the re-read did not get through, or it did and part of it could not be written down. mirror_stale_reason says which. Treat it as a reason to read again, never as a sign the act failed.
Present whenever mirror_refreshed is, and null when it is true — an absent field would leave you inferring that nothing is wrong.
provider_reread_failed — the gateway was not reachable after it accepted the act. Nothing above was updated; read again.
price_not_mapped_to_provider — the gateway named a price that is not mapped onto any price in this catalogue for this environment, so plan_id was left as it was while everything else was applied. This one matters: entitlements are computed from the plan, so until you map the price (see unmapped_provider_price_id) the customer keeps the plan they were on. Prices created in the gateway's own dashboard are the usual cause.
subscription_has_extra_lines — the gateway holds more priced lines than one, so which of them names the plan is not decidable and both plan_id and items were left as they were.
provider_reread_failed, price_not_mapped_to_provider, subscription_has_extra_lines, null The gateway's own price id to map, when mirror_stale_reason is price_not_mapped_to_provider. Null otherwise.