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.
```
cmuxPlan
```
in Stack
```
clientReadOnlyMetadata
```
is the only entitlement VM code reads; a
```
cmuxVmPlan
```
manual override wins.
```
resolveProPlanStatus
```
ORs legacy Stack products with active
```
stripe_subscriptions
```
rows.
```
/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
```
.
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.

Test-mode resources

Product

prod_UpIQRE6cj0nFjs

. New checkouts use

cmux-pro-monthly

($30/mo) and

cmux-pro-yearly-288

($288/yr, equivalent to $24/mo). Keep

cmux-pro-yearly

($240/yr) active for grandfathered subscriptions. Staging webhook endpoint

we_1Tq1SZGhInAdn3JbWJReKNEN

forwards to

cmux-staging.vercel.app

; its secrets are already in the

cmux-staging

Vercel project.

Feature flags

pro-upgrade-ui-enabled-release

(PostHog id

) gates all Pro UI and stays OFF in release until launch; DEBUG builds default it on. 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
```
.

cmux-billing

NPX Install

Tags

SKILL.md Content