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 staff-only /api/admin/* routes let admins (a verified cmux.com, manaflow.ai, or manaflow.com email, or a verified email with an active admin_members row) search users, teams, and emails and: 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/routeAuth.ts requireAdmin is the gate (domain check in services/admin/access.ts); members, audit, and pro-users routes manage admin invites, the audit log, and the Pro roster. 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; the admin UI is not part of this repository and 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

• Use web/scripts/stripe/dev-stack.sh.
• Local bun dev accounts use the development Stack project and receive a non-persistent Pro entitlement automatically. This applies only when CMUX_LOCAL_DEV_PRO=1, NODE_ENV=development, VERCEL_ENV is unset, and NEXT_PUBLIC_STACK_PROJECT_ID is the development project. Release and preview deployments remain billing-backed. Use dev-grant.sh only when testing an explicit manual grant or a non-local deployment.
• The tagged app bakes CMUX_PORT into Info.plist; run the dev server on the tag's printed port, never a hardcoded one.
• Per-branch Docker Postgres ports collide with other agents' containers. Use --db-port and never stop containers you did not create.
• /app-pricing requires cmux_app=1. cmux_scheme threads the native deeplink return scheme; cmux-dev-* schemes are honored only for localhost requests.
• Repeat dogfood: use a private window for a fresh anonymous buyer, and web/scripts/stripe/dev-reset.sh <email> to un-Pro a signed-in dev account before retesting checkout.
• Fake payment, two ways: web/scripts/stripe/dev-grant.sh <email> writes cmuxVmPlan: "pro" directly (same override as /api/admin/users) (instant, no checkout; undo with dev-reset). For the full checkout path at $0, enter promotion code CMUXDEV100 in test-mode checkout: a 100%-off forever coupon in the test account; allow_promotion_codes is already set on checkout sessions.
• Newer Stripe CLI prints stripe config --list as key=value (older builds used key = 'value'); dev-stack.sh and dev-reset.sh accept both. If key extraction fails, re-run stripe login.

Catalog

Prices live in web/services/billing/plans.ts and are provisioned by web/scripts/stripe/provision-catalog.sh. Current checkout keys: cmux-go-monthly-10 ($10/mo), cmux-pro-monthly-50 ($50/mo), cmux-pro-yearly-480 ($480/yr, $40/mo equivalent), cmux-max-monthly-200 ($200/mo), cmux-max-yearly-1920 ($1,920/yr, $160/mo equivalent), and cmux-team-monthly-60 ($60/user/mo). Pro and Max use the same 20% annual discount. Go and Team remain monthly-only. Go and Max are personal plans like Pro: the user-scoped subscription row's plan column is derived from its Price lookup key (personalPlanIdForSubscription), cmuxPlan mirrors the exact purchased plan, and every isPro check passes. Every Max and Pro CTA links /api/billing/checkout, and web/services/billing/personalSwitchRoute.ts decides where an existing subscription goes (the portal route uses the same function for old flow=switch_plan links, so the two never disagree or loop). A monthly subscription on a price the switch portal lists (PORTAL_SWITCHABLE_LOOKUP_KEYS: Pro monthly and both Max intervals) opens Stripe's subscription-update flow with the portal configuration stamped metadata.purpose=personal_plan_switch (the script provisions it; the account default configuration stays quantity-only). A yearly, grandfathered or Go subscription opens the dashboard's switch dialog (/dashboard/billing?change=max), which keeps the billing interval and prices any subscription. An account with no subscription to switch (an operator grant, a company account or Founder's Edition) buys Max through a new Checkout. Founder's Edition is a one-time purchase of Pro for life, stored as an active Pro row marked founders_edition; it is never a subscription to switch or cancel. A founder on Max returns to Pro by cancelling Max (the dashboard's Pro card opens that cancel dialog), never by switching onto a paid Pro price, and planChange.ts refuses that switch. Stripe amounts are immutable, so a price change mints a new lookup key carrying the amount and adds the old key to LEGACY_PRICE_LOOKUP_KEYS; grandfathered Prices (cmux-pro-monthly $30, cmux-pro-yearly $240, cmux-pro-yearly-288 $288, cmux-team-monthly $35, cmux-team-yearly-336 $336, cmux-team-yearly-576 $576) stay active for the subscriptions on them and /dashboard/billing prices every row from its own Stripe amount. Env price-id overrides carry the amount in their name (STRIPE_PRO_MONTHLY_50_PRICE_ID, STRIPE_PRO_YEARLY_480_PRICE_ID, STRIPE_MAX_MONTHLY_200_PRICE_ID, and STRIPE_MAX_YEARLY_1920_PRICE_ID); a retired name fails env validation, so delete it from Vercel before deploying a price change. Test-mode Pro product prod_UpIQRE6cj0nFjs (Max prod_VOppwEzT7jtBNW; Max monthly price_1UO29QGhInAdn3JbD2Cld8PX, annual price_1UOl71GhInAdn3JbYWi9kguZ; switch portal bpc_1UO2AIGhInAdn3JbgNBD6OZD); live Pro product prod_Uq4a28vk0fP3E6; live Max product prod_VEpRwst8UwD5cm (Max monthly price_1UELmdGhInAdn3Jb8Gpe9ilK, annual price_1UOl9ZGhInAdn3Jb8g9BoXSx, switch portal bpc_1UELmeGhInAdn3JbgZqLIbP0). STRIPE_PERSONAL_PLAN_SWITCH_PORTAL_CONFIGURATION_ID is pinned in Vercel (production = live id, development and preview = test id) so the restricted production key never has to list portal configurations. Staging webhook endpoint we_1Tq1SZGhInAdn3JbWJReKNEN forwards to cmux-staging.vercel.app; its secrets are already in the cmux-staging Vercel project.

The paid Cloud VM allowance lives in web/services/vms/machineSpec.ts and web/services/vms/entitlements.ts. A paid seat buys up to 5 active Cloud VMs that share vCPU and RAM pools: Pro and Founder's Edition share 20 vCPUs and 40 GB RAM; Max shares 80 vCPUs and 160 GB RAM. Team has one team pool of 20 vCPUs and 40 GB RAM per paid seat (multiplied by cmuxSeats like the 5-VM count) shared by every member, not a separate allowance per user. The user divides the pool however they like. Only provisioning and running VMs count against it; paused and stopped VMs do not. Disk is a per-VM limit and is not pooled: Go grows to 16 GB, Pro/Team/Founder's to 128 GB, and Max to 256 GB. The largest single VM is 8 vCPU / 16 GB RAM (the lg row) on Pro, Team, and Founder's, and 32 vCPU / 64 GB RAM (the 2xl row) on Max (maxMemoryMbForPlan). Go stays at one 2 vCPU / 4 GB VM. The default machine has 8 GB RAM and 32 GB disk. The repository enforces both the machine count and the pool under the billing-team lock on create, Base open/reset, paused resume, resize, and fork, using each VM's stored resource reservation (legacy rows without a marker conservatively reserve the provider maximum until reconciliation measures them). A request over the pool fails with a typed resource-pool error that names the pool, the amount in use, and the request; GET /api/vm limits publish the pool and its usage. The machine list publishes lockedMemoryOptionsMb and memoryUpgradePlanId, and a create that asks for a locked size gets 402 vm_memory_requires_plan instead of a silently smaller machine. Pricing copy must say the resources are pooled, never per VM. Paid-limit environment overrides are retired; the create kill switch remains the incident control.

Pro and Max sell yearly: interval=year&plan=pro checks out cmux-pro-yearly-480 ($480/yr, 20% off; env override STRIPE_PRO_YEARLY_480_PRICE_ID) and interval=year&plan=max checks out cmux-max-yearly-1920 ($1,920/yr, 20% off; env override STRIPE_MAX_YEARLY_1920_PRICE_ID). Go and Team interval=year requests return annual_unavailable before creating Stripe state, and their historical annual prices stay active only for existing subscriptions. The personal plan-switch portal lists Pro monthly and both Max intervals; yearly subscribers switch in the dashboard instead. The Pro and Max pricing cards own the billing period, so each plan's price, checkout link, and CTA analytics (interval, discount_percent) always agree.

Feature flags

Pro upgrade entrypoints and public pricing navigation no longer use a rollout flag. The sidebar badge still respects its local dismissal preference. Public Pro and Team pricing CTAs always route through /api/billing/checkout, never the download confirmation page. cmux __internal_flags, once merged, inspects and overrides flags locally.

Prod runbook

Run web/scripts/stripe/provision-live.sh with an operator key, add the two Vercel envs, deploy, validate live with a 100-percent-off promotion code purchase, then cancel.

DB migrations: bun run cloud-vm:preflight, bun run cloud-vm:migrate -- staging, staging deploy, then bun run cloud-vm:migrate -- production. Never run migrations from builds. See the Cloud VM ops flow.

Gotchas

• bun mock.module is process-global, so every module mock must carry every real export other suite files import. A missing export can surface only in CI's test order as Export named X not found.
• Tests must not depend on DATABASE_URL being set.
• drizzle-1.0-beta wraps pg errors in DrizzleQueryError; read error.cause for the pg code and constraint.
• Pages outside app/[locale] need a proxy.ts bypass (like /app-pricing and /billing), or next-intl rewrites them into the locale tree and they 404 through missing root layout tags. Those subtrees also need their own layout with html and body.