# Usage, billing, and webhooks

Read usage and subscription state while keeping browser flows, metering, and provider events separate.

Source: https://docs.minds.sh/docs/api/platform/billing-usage



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 [#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 [#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 [#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 [#incoming-webhooks]

The source includes separate webhook integrations:

* Dashboard: `/api/webhooks/stripe`.
* Management service: `/api/webhooks/billing` and `/api/webhooks/billing/stripe`.
* Auxiliary API application: `/webhooks/auth` and `/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 [#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](/docs/api/platform/endpoints) 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.