Get Subscription
Read an organisation's current subscription.
Use this on a billing screen to show the plan, its renewal date, and whether it is set to stop.
โถ200 with null means "no subscription", and is not an error
200 with null means "no subscription", and is not an errorAn organisation on pay-as-you-go returns 200 with data: null. This
endpoint never returns 404 for "no subscription". Handle the null and
render your pay-as-you-go state.
A 404 means something different: the organisation id is not one this key
can see. The same status is returned whether the organisation does not exist
or belongs to someone else.
โถSingular by design
An organisation can hold only one subscription, which a database constraint
enforces. The path says subscription, not subscriptions, so there is no
collection to page through.
โถFields
| Field | Meaning |
|---|---|
plan_key | The plan key, normally starter, growth or pro. |
status | The live subscription's state: pending while a checkout is in flight, incomplete / trialing / active once Stripe has it, and past_due / unpaid while payment is being retried. A canceled, paused or expired subscription is not live โ this route returns null for it, so those values never appear here. |
current_period_end | When the paid period ends. null while pending, because there is no period yet. |
cancel_at_period_end | true when the subscription stops at current_period_end. The status stays active until then. |
included_units | Supplier locations the plan credits per year. null for a negotiated plan outside the three self-serve tiers. |
โถThis is not the same as plan_key on the credits endpoint
plan_key on the credits endpointGET /organizations/:id/credits also returns a plan_key. That one is a
summary for a stage header. This endpoint is the lifecycle detail โ status,
renewal date, and pending cancellation โ for a billing screen.
They are not wired together yet. /credits currently returns
plan_key: null for every organisation, whatever this endpoint reports. Once
subscriptions can be bought, an organisation on a plan will read its real
plan_key here and still read null from /credits until a follow-up
ticket wires that field to the same row. Read the plan from this endpoint,
not from /credits.
โถErrors
| Status | Meaning |
|---|---|
| 400 | The id is not a UUID. |
| 401 | Missing or invalid API key. |
| 403 | The key does not hold billing:read. |
| 404 | The organisation is not in this key's scope. Never returned for "no subscription". |
Required scope:
billing:read