REST surface for the billing tab — subscription, usage, portal, addons, checkout, metering toggle, wallet, and the wallet top-up checkout.
API reference
Every endpoint is tenant-scoped. The platform derives the
tenant_id from the JWT; you never pass it in the body or in
a path segment.
Tenant JWT in the Authorization: Bearer … header. Endpoints
return 401 if the JWT is missing or invalid, 403 if the
caller lacks the billing permission for their role.
| Method | Path | Purpose |
|---|
| GET | /api/v1/tenant/billing/subscription | Current Stripe subscription status and period boundary. |
| GET | /api/v1/tenant/billing/usage | Current-period roll-up: tier base + metered events + total. |
The unavailable response shape. Both /subscription
and /usage (and /wallet, see below) can return a body
shape indicating the surface is "unavailable" for this tenant
— typically a Solo-tier tenant with no subscription row yet,
or a tenant whose org hasn't been wired into the billing
back-end. The frontend renders an empty state in this case;
clients integrating with the API should handle the
unavailable body as a valid 200 response, not a failure.
| Method | Path | Purpose |
|---|
| GET | /api/v1/tenant/billing/portal | Returns a short-lived Stripe Customer Portal session URL. |
| Method | Path | Purpose |
|---|
| GET | /api/v1/tenant/billing/addons | List the tenant's active paid and free add-ons. |
| DELETE | /api/v1/tenant/billing/addons/:addon_key | Disable a free add-on. (Paid add-ons cancel through the portal.) |
| Method | Path | Purpose |
|---|
| POST | /api/v1/tenant/billing/checkout | Start a Stripe Checkout for a tier upgrade. Returns a session URL. |
| POST | /api/v1/tenant/billing/checkout/addon | Start a Stripe Checkout for a paid add-on. Returns a session URL. |
| Method | Path | Purpose |
|---|
| POST | /api/v1/tenant/billing/metering | Toggle whether the tenant is opted into metered event capture. |
| Method | Path | Purpose |
|---|
| GET | /api/v1/tenant/billing/wallet | Current org wallet balance and last-alerted-at marker. |
| POST | /api/v1/tenant/billing/wallet/topup-checkout | Start a Stripe Checkout for a wallet top-up. Returns a session URL. |
The wallet endpoints answer for the org that owns the calling
tenant. A tenant that doesn't belong to a metered org gets
the unavailable shape, same as the subscription endpoints.