Most read endpoints have no explicit permission (any tenant member can see their own plan/usage); management actions require billing.manage or billing.view.
| Method & Path | Permission | Purpose | Side effects |
|---|---|---|---|
GET billing/plans | — | Plans with FX-resolved pricing | — |
GET billing/subscription | — | Active subscription + entitlements | — |
GET billing/usage | — | Usage vs plan caps | — |
GET billing/transactions | billing.view | Billing transaction history | — |
GET billing/invoices / GET billing/invoices/{uuid} | billing.view | List / detail | — |
GET billing/invoices/{uuid}/pdf / /receipt | billing.view | Stream invoice PDF / payment receipt PDF (paid only) | — |
POST billing/invoices/{uuid}/retry | billing.manage | Reopen checkout for an outstanding invoice | Calls gateway checkout |
POST billing/discount/preview | billing.manage | Preview a promo code (never throws) | — |
POST billing/quote | billing.manage | Build a server-authoritative, time-locked checkout quote | Persists a BillingQuote; 422 if live FX is unavailable |
POST billing/subscribe | billing.manage | Subscribe or change plan | Requires TOTP for paid plans; identity step-up for a paid→free downgrade |
POST billing/checkout/sync | billing.manage | Verify a pending checkout with the gateway directly | Webhook-loss fallback; idempotent against the webhook path |
GET billing/addons | — | Add-on catalogue (extra users; transaction blocks on Growth) — add-ons recur with the plan | — |
POST billing/addons | billing.manage | Set add-on quantities | Decreases apply immediately; increases return a checkout URL for a prorated charge, after which the add-ons recur on every renewal invoice |
POST billing/subscription/{subscription}/cancel | billing.manage | Cancel (immediate or at period end) | — |
Platform admin billing
| Method & Path | Purpose |
|---|---|
GET admin/plans, POST admin/plans, PATCH admin/plans/{plan} | Plan CRUD |
DELETE admin/plans/{plan} | Delete (or deactivate if in use) |
POST/PATCH/DELETE admin/plans/{plan}/prices/{price} | Per-country/interval price rows |
GET admin/billing/reconciliation | Cross-tenant invoice ↔ payment ↔ gateway settlement matching |
GET/POST/PATCH/DELETE admin/discounts | Promo code CRUD |
All /admin/* routes require the platform middleware, independent of tenant RBAC. See API — Platform Admin.