cmux Billing

Read before changing billing, pricing, Stripe, Pro entitlement, checkout, webhook, or subscription code.

Architecture map

• /api/billing/checkout creates Stripe Checkout Sessions for Pro when STRIPE_SECRET_KEY is set. It sets client_reference_id to the Stack user id, auto-creates an anonymous Stack user for signed-out buyers, and falls back to the legacy Stack purchase path when Stripe is unset or plan=team. The "already active" short-circuit lives here.
• /api/billing/portal resolves the current Stack user, looks up their stripe_customers row, and creates a Stripe customer portal session returning to /pricing.
• /api/billing/subscription cancels or resumes the active Stripe Pro subscription; /dashboard/billing renders localized in-dashboard plan state and self-serve actions.
• web/services/billing/purchase.ts is the shared idempotent recorder used by /api/billing/complete and /api/stripe/webhook. It attaches email to the purchaser, records billing_email_claims on conflict, and never cross-grants based on an unverified email.
• VM code reads the plan from Stack clientReadOnlyMetadata: a non-empty cmuxVmPlan (operator override) takes precedence, otherwise cmuxPlan (the Stripe mirror) supplies the entitlement. resolveProPlanStatus reports Pro for an active stripe_subscriptions row or a paid cmuxVmPlan override (pro, team, founders); billingManagement stays Stripe-only, so a granted account shows Pro without a portal link.
• The private cmux-admin app (https://cmux-admin.vercel.app/pro, source admin/ in cmuxterm-hq) lets verified cmux.com, manaflow.ai, and manaflow.com accounts search users, teams, and emails and, after a confirmation dialog: grant or remove the user cmuxVmPlan override (/api/admin/users), grant or remove a team override of team (/api/admin/teams), grant Pro to an email with no account yet (/api/admin/email-grants, stored in admin_plan_grants and applied by the after-sign-in callback once the mailbox is verified), and downgrade a paying customer by cancelling the Stripe subscription at period end (/api/admin/subscriptions, same service as the self-serve form). services/admin/access.ts is the gate, services/admin/proGrants.ts writes under the account-mutation lease and records serverMetadata.cmuxAdminPlanGrant (who, when, which plan). Non-admins get 403 on the API; there is no admin page on cmux.com. The admin_plan_grants migration is an operator step; until it runs, pending email grants report 503 and search omits them.
• /api/stripe/webhook is signature-verified, insert-first idempotent through stripe_webhook_events, safe for foreign events in the shared Stripe account, and gates cmux handling on metadata.app === "cmux". Return 2xx only after durable writes; return 500 to make Stripe retry.

Dev workflow