billing
GET /v1/entitlements
What this organization's plan grants, and how much of it is used.
Authentication
Send an API key as a bearer token. The key must carry the billing.view permission; a key without it is refused with 403, not 404.
Where your organisation id goes
This endpoint takes org_id as a query parameter. Leave it out and the call covers your whole tenancy subtree; send it to narrow the call to one organisation.
Your organisation id is on the API keys screen in your dashboard, beside the key itself. It is the same id in every call you make.
Try it
Replace anything in angle brackets with your own values, and the key placeholder with a key from your dashboard.
curl -X GET https://api.zinndigital.com/v1/entitlements \
-H "Authorization: Bearer zdk_live_…"Signed in? The API console in your dashboard fills in your real organisation id and your own key, and runs the request against the live API so you can see the actual response. Open this endpoint in the API console
Details
The customer-facing half of entitlement enforcement (#2726). Returns every **counted allowance** the engine refuses on — with `used`, `limit` and `remaining` — and every **boolean feature** it gates on, marked included or not. A cap the engine refuses on and the customer cannot see is a cap nobody can plan around: the first they learn of it is the moment it stops them. So the numbers here are the same numbers the refusal quotes. `limit` distinguishes three states (docs/144 §1) and they are **not** interchangeable: `-1` means the plan sold "unlimited" and says so; a non-negative integer is a real cap; **`null` means the plan states no cap at all**, which is neither a promise nor a limit and is the normal case — only 8 of 134 live plans state `team_seats`. `enforced` is the single field a client should branch on to decide whether to draw a usage bar. Resolution walks the organization tree: a reseller's client org holds no subscription of its own, so the answer comes from the nearest ancestor that grants one, and `entitling_org_id` names it. Requires `billing.view`.
Parameters
| Name | Type | Required | What it is |
|---|---|---|---|
org_id (query) | Uuid | No | The organization to report on; defaults to the caller's own. |
Response
| Name | Type | Required | What it is |
|---|---|---|---|
entitling_org_id | Uuid | Yes | The organization whose plan grants these — the caller's own org or an ancestor. Null when nothing in the chain grants anything. |
source | string<staff, subscription, none> | Yes | Where the grant came from. The customer's next move differs: a `staff` grant is not upgradable, a `subscription` one is, and `none` means there is nothing to upgrade *from* — bu… |
plan_name | string | Yes | — |
has_plan | boolean | Yes | — |
allowances | EntitlementAllowance[] | Yes | — |
features | EntitlementFeature[] | Yes | — |
Errors this endpoint can return
401 · 403 · 429