Stripe Billing Go-Live Runbook

Turning on paid subscriptions (#251). The billing code is merged (#390 + #392) but dormant until configured — isBillingEnabled() is false with no STRIPE_SECRET_KEY, so the UI hides billing actions and the webhook route returns 503. This runbook is the wiring + verification to actually charge cards.

🎯 What's already built

• Service: packages/trpc/src/services/billing/stripe.ts — hosted Checkout + Customer Portal, Stripe customer per org, price resolution from stable lookup_keys. No card data touches our servers.
• Webhook: packages/trpc/src/services/billing/stripeWebhook.ts + route apps/api/src/routes/webhooks.ts → POST /api/webhooks/stripe. Signature-verified; reconciles organizations.tier from subscription state.
• tRPC: organizations.createCheckoutSession / createPortalSession (owner/admin only).
• Web: the org Usage page shows Manage plan (portal) when subscribed, else a monthly/annual toggle + Upgrade buttons.

organizations.tier (free / hobby / team / pro) stays the gating source of truth; Stripe reconciles it.

✅ Pre-launch checklist

1. Create products + prices in live Stripe

Each paid tier needs a price per interval, tagged with a stable lookup_key. The code resolves prices only by these keys (never raw price_… ids), so they must match exactly:

Set the Lookup key field on each price (Dashboard → Product → price → Advanced, or --lookup-key via the API). Create the same six in test mode first for verification. Rotating a price later — archive the old, create a new one with the same lookup_key — needs no code or env change.

2. Activate the Customer Portal

Dashboard → Settings → Billing → Customer portal: enable it and allow plan switching + cancellation. createPortalSession fails until the portal is configured (separately in test and live).

3. Set environment variables (prod / Railway)

Also confirm APP_URL is the real public web origin: Checkout redirects to ${APP_URL}/organizations/<slug>/usage?checkout=success|cancelled and the portal returns to the same Usage page. A wrong APP_URL sends paying users to a dead link after payment.

⚠️ ENFORCE_RUN_QUOTA=true is not optional for a paid launch. Left unset/false, the run-quota gate only meters and warns — the free tier is effectively uncapped, so paid tiers buy nothing. Flip it on at launch.

4. Register the webhook endpoint

Dashboard → Developers → Webhooks → Add endpoint:

• URL: https://<api-host>/api/webhooks/stripe
• Events:
  • checkout.session.completed
  • customer.subscription.created
  • customer.subscription.updated
  • customer.subscription.deleted

Copy the endpoint's signing secret into STRIPE_WEBHOOK_SECRET (step 3) and redeploy the API.

5. Apply the database migrations

The Stripe columns ship in two migrations — apply both in prod:

• 0021_tranquil_jackpot.sql — stripe_customer_id, stripe_subscription_id, stripe_subscription_status + index
• 0022_typical_tomorrow_man.sql — stripe_cancel_at_period_end

pnpm db:migrate   # runs outstanding Drizzle migrations

🧪 Verify against test Stripe first

Do a full dry run in test mode before pointing prod at live keys.

# Forward test webhooks to the local API (port 4000)
stripe listen --api-key sk_test_… \
  --forward-to localhost:4000/api/webhooks/stripe
# → prints the whsec_… to use as STRIPE_WEBHOOK_SECRET locally

Walk the lifecycle and assert organizations.tier after each step:

1. Upgrade — from the Usage page, Upgrade to a tier → complete Checkout with test card 4242 4242 4242 4242. Expect checkout.session.completed + customer.subscription.created → tier flips to the purchased tier.
2. Manage — Manage plan opens the portal; switch interval/tier → customer.subscription.updated → tier tracks the new price.
3. Cancel — cancel in the portal → on period end customer.subscription.deleted → tier returns to free.
4. Replay/idempotency — stripe events resend <evt_id> lands the same row state (the webhook re-fetches the subscription fresh, so reconciliation is order- and replay-independent).

stripe trigger customer.subscription.deleted etc. can drive these without real card flows.

🔎 Behaviours worth knowing (so prod surprises don't look like bugs)

• past_due keeps access. isActiveSubscriptionStatus counts active, trialing, and past_due as active — a card being retried doesn't instantly lose the paid tier. Dunning is left to Stripe; access drops only on terminal cancellation.
• Unknown lookup_key ≠ downgrade. If an active subscription's price has no recognised lookup_key (a misconfigured price), the webhook holds the current tier and logs active subscription has unrecognised price lookup_key at error level rather than silently dropping the org to free. If you see that log, fix the price's lookup_key in the dashboard (step 1). Watch for it after any price change.
• Webhook failures retry. Any handler error (incl. transient DB blips) returns non-2xx, so Stripe retries — expected. A persistent 400 means a bad signature (wrong STRIPE_WEBHOOK_SECRET) or unconfigured billing (503).

🔁 Rollback

Billing is feature-flagged by config: unset STRIPE_SECRET_KEY (and redeploy) to make the module dormant again — UI hides billing, the webhook 503s. Existing organizations.tier values are untouched, so already-provisioned orgs keep their tier until you reconcile manually. The migrations are additive (nullable columns) and need no rollback.