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

An 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

FieldMeaning
plan_keyThe plan key, normally starter, growth or pro.
statusThe 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_endWhen the paid period ends. null while pending, because there is no period yet.
cancel_at_period_endtrue when the subscription stops at current_period_end. The status stays active until then.
included_unitsSupplier 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

GET /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

StatusMeaning
400The id is not a UUID.
401Missing or invalid API key.
403The key does not hold billing:read.
404The organisation is not in this key's scope. Never returned for "no subscription".

Required scope: billing:read