Get Subscription Catalogue
Read the self-serve tier catalogue, priced.
Use this to render a plan-selection stage. It returns every tier with its price, what the tier includes, and the saving against pay-as-you-go.
โถWhy this is organisation-scoped
A negotiated tier for one customer is already possible, so the catalogue is
read per organisation rather than from a global /plans route. Today every
organisation in scope sees the same three tiers.
โถThe amount is verified against Stripe before it is served
The price comes from our SKU table, and Stripe is checked to agree with it on
every read. When the two disagree the whole catalogue returns 503
PRICE_DRIFT rather than a figure. You will never be shown a price that
checkout would then refuse to honour.
This means a price change needs a deploy to appear here. That is deliberate: one source of truth for the displayed and the charged amount.
โถFields
| Field | Meaning |
|---|---|
currency | ISO currency code. Always usd today. |
key | Tier key: starter, growth or pro. Pass this to checkout. |
name | Display name. |
lookup_key | The Stripe lookup key. The price id is never exposed. |
unit_amount | Annual price in the minor unit โ 100000 is $1,000.00. |
interval | Billing interval. Always year today. |
included_units | Supplier locations the tier credits per year. |
seats | Returned for display. Nothing enforces it. |
compare_at_amount | What included_units would cost at the pay-as-you-go rate. Use it as the struck-through price. |
savings_pct | The discount against compare_at_amount, rounded to a whole percent. |
included | The lines to render on the tier card. The same shape the checkout response returns, so one renderer serves both. |
โถincluded[] and quantity: null
included[] and quantity: nullA null quantity means unlimited, not zero and not unknown. DDS
generation and submission are unlimited on every tier, so that row always
carries null.
โถ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. |
| 503 | STRIPE_UNAVAILABLE, PRICE_NOT_SEEDED or PRICE_DRIFT. Retry; never fall back to a price of your own. |
The three 503 codes are distinct on purpose. STRIPE_UNAVAILABLE means
billing is not configured in this environment. PRICE_NOT_SEEDED means the
Stripe account is missing a tier price. PRICE_DRIFT means Stripe and our
SKU table disagree on an amount.
Required scope:
billing:read