Billing states: plans, seats, grandfathering and "not configured"
Status: seat checkout, plan enforcement and refund records are ON in code
(BILLING_SEAT_CHECKOUT_ENABLED, BILLING_PLAN_ENFORCEMENT_ENABLED, BILLING_REFUND_ADMIN_ENABLED, all true),
for orgs that are NOT grandfathered. Nothing ever charges or refunds automatically without Stripe configured.
Which state an org is in
| State | Who | What they see |
|---|---|---|
| Grandfathered: internal plan | every org whose plan is internal. New orgs are still created on internal (migration 9520, pre-launch decision D6, docs/BILLING-PLANS.md), so this is the default | everything unlimited; no seat picker; never enforced (planEnforcement.reason grandfathered_*) |
| Grandfathered: created before the cutoff | orgs created before BILLING_GRANDFATHER_CUTOFF (2026-10-04T00:00:00Z; all of production's existing orgs) | never enforced, not offered seat checkout |
| Billable | an org on free / pro / enterprise created at or after the cutoff | the seat picker (seatCheckout on GET /v1/orgs/{orgId}/entitlements); an invite past the PAID seats is 403 billing_seats_exceeded |
| Not configured | any org on a deployment without STRIPE_SECRET_KEY / price ids | checkout 501 billing_not_configured; the billing page says self-serve billing is not switched on yet |
| AI: bring your own key | a billable org with 0 AI tokens | must store its own OpenRouter key for AI features and embeddings (vector memory); without one, embedding_key_required |
Usage metering (usage.metering, on) records costs per org and an advisory budget (GET /v1/orgs/{orgId}/usage,
PUT .../usage/budget, MCP usage_get; agent model spend: usage.md); it charges nothing. Refund requests are platform-admin records and
decisions only (/v1/admin/billing/refund-requests, not in the public document).
For an agent
Never tell a person they will be charged, refunded or upgraded. Read GET /v1/orgs/{orgId}/entitlements for the
truth about an org; a 501 billing_not_configured means the deployment, not the person, is missing something.
Billing changes are always a person's act and, for production, an owner decision.
Reference
- API reference: tag
billing(/orgs/{orgId}/entitlements,/orgs/{orgId}/billing/checkout,/orgs/{orgId}/billing/portal) and/orgs/{orgId}/usagein/v1/openapi.json. - MCP tools:
usage_get,usage_model_summary,usage_model_record(usage, see usage.md); billing has no tools by design. See the MCP tool reference.