Billing API

These authenticated endpoints expose the current hosted implementation. Credits are usage units; they are not cash or stored value.

Get usage summary

GET /api/usage?period=month returns the signed-in user's usage summary. period may be day, week, or month.

{
  "totalCostCents": 1247,
  "totalInputTokens": 284000,
  "totalOutputTokens": 98000,
  "byModel": [
    {
      "modelId": "anthropic/claude-sonnet-4",
      "costCents": 876,
      "inputTokens": 200000,
      "outputTokens": 70000
    }
  ],
  "periodStart": "2026-07-09T00:00:00.000Z",
  "periodEnd": "2026-08-09T00:00:00.000Z"
}

Get current tier

GET /api/tier returns the signed-in user's primary organization, plan, features, limits, and remaining/monthly credits.

{
  "plan": "pro",
  "organizationId": "org_abc123",
  "hasStripeCustomer": true,
  "canManageBilling": true,
  "features": [],
  "limits": {},
  "credits": { "remaining": 3753, "monthly": 5000 },
  "upgradeUrl": "/pricing"
}

The hosted service currently pauses usage when the plan allocation is exhausted. Metered or invoice overage is not enabled.

Pro Checkout endpoint (suspended by default)

POST /api/stripe/checkout accepts:

{
  "organizationId": "org_abc123",
  "plan": "pro"
}

The endpoint returns 503 unless SELF_SERVICE_CHECKOUT_ENABLED=true after the operator and consumer flow are validated. When enabled, the caller must be an organization owner or admin and must have a current legal acceptance record.

Access the billing portal

POST /api/stripe/portal accepts:

{ "organizationId": "org_abc123" }

The caller must be an organization owner or admin. The response contains the Stripe-hosted Customer Portal URL. Cancellation access is not conditioned on accepting a new version of the Terms.

Stripe webhook

POST /api/stripe/webhooks validates Stripe's signature and processes subscription lifecycle events. Event-ID deduplication and transactional, invoice-keyed credit grants remain open controls; the handler must not be described as idempotent until those controls are implemented and tested.

Common responses