Usage, billing, and webhooks
Read usage and subscription state while keeping browser flows, metering, and provider events separate.
Usage describes work and retained state. Subscription records describe billing arrangements. Neither a dashboard fallback nor an accepted webhook is proof that a charge has settled.
Read instance usage
The management API exposes:
| Endpoint | Purpose |
|---|---|
GET /api/v1/tenants/[id]/usage | Usage response for an authorized tenant |
GET /api/v1/tenants/[id]/metrics | Time-series metrics query defined by its request schema |
GET /api/v1/tenants/[id]/status | Tenant status and health summary |
Each route resolves authentication and tenant access. The source schemas include legacy request, storage, and plan fields; keep their units and time windows intact when presenting results. Current Minds packaging uses dedicated Free, Pro, and Enterprise, with compute, retained storage, and transfer as the usage dimensions. Legacy Mind Units fields do not define the current billing model. A legacy schema field is not a new billable SKU.
Read subscriptions in the dashboard
GET /api/billing/subscriptions requires a browser session. It chooses a tenant from the orgId query, active tenant cookie, session tenant/org IDs, or user ID, then queries the configured billing service with the session access token.
The route returns {subscriptions:[]} when that fetch fails. An empty result can therefore mean unavailable billing data; do not tell the user they have no subscription solely from this response.
Checkout and account management
POST /api/billing/action accepts these actions:
| Action | Required payload fields | Response |
|---|---|---|
checkout | tenantId, plan, successUrl, cancelUrl | {url, sessionId} |
portal | tenantId, returnUrl | {url} |
cancel | tenantId | {success:true}; requests cancellation at period end |
reactivate | tenantId | {success:true} |
The route delegates to the payments integration. Its module does not itself perform the standard getSession() organization check, so it should not be treated as a documented public customer API-key interface. Access enforcement and deployment exposure require the configured payments and routing controls.
Incoming webhooks
The source includes separate webhook integrations:
- Dashboard:
/api/webhooks/stripe. - Management service:
/api/webhooks/billingand/api/webhooks/billing/stripe. - Auxiliary API application:
/webhooks/authand/webhooks/payments.
These are provider/server event ingress points. Use the exact signature, event type, and environment configuration in each endpoint contract; do not call them with a customer instance token or fabricate a successful event body.
A webhook receiver acknowledging an event proves only that the receiver accepted it. Confirm the resulting tenant/subscription state and provider receipt before reporting a completed billing transition.
Operational telemetry
The auxiliary API exposes /health, /api/health/detailed, and /api/metrics, and a /cron/keep-alive route. The management service has /api/status. Their deployment origins and access controls differ from the customer Mind endpoint. The catalog documents their actual implementations without treating all of them as public customer endpoints.
Source: dashboard billing routes, management tenant usage/metrics routes, and the independently deployed webhook modules.