skills.rest
manaflow-ai
manaflow-aiOFFICIAL
Explore all skills by this author →
GitHub

cmux-billing

Guides Stripe checkout, subscription, webhook, and Pro entitlement work for cmux billing.

26.6k|2.3k|Updated Jan 28, 2026
Search Tags:#webhook#stripe#Checkout#Billing#entitlement#Runbook#Subscription
One-click install
npx skills add https://github.com/manaflow-ai/cmux --skill cmux-billing
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: cmux-billing
Source: https://github.com/manaflow-ai/cmux/tree/main/skills/cmux-billing
Command: npx skills add https://github.com/manaflow-ai/cmux --skill cmux-billing

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Billing work in cmux spans Stripe Checkout, Stack authentication, webhook handling, and entitlement metadata, and mistakes in any of these paths can break payments or grant incorrect Pro access. This Skill provides the architecture map, dev workflow, and production runbook needed to change billing code safely.

Core Features & Use Cases

  • Architecture Map: Documents the checkout, portal, subscription, and webhook API routes plus the shared idempotent purchase recorder and entitlement resolution logic.
  • Dev Workflow: Covers the dev-stack script, per-branch Docker Postgres ports, fake payment paths via dev-grant or the CMUXDEV100 promotion code, and dogfooding reset procedures.
  • Production Runbook: Details live provisioning, Vercel environment setup, staged database migrations, and feature flag gating for the Pro upgrade UI.
  • Use Case: When adding a new yearly pricing tier, follow the Skill to create the Stripe price, update checkout routing, test with a 100%-off promotion code in test mode, and run the staged migration sequence before production deploy.

Quick Start

Read the cmux-billing skill before modifying any Stripe checkout, webhook, subscription, or Pro entitlement code in the cmux repository.

Frequently Asked Questions about cmux-billing

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I test Stripe checkout locally without a real payment?▼

Use web/scripts/stripe/dev-grant.sh <email> to write cmuxPlan pro directly for instant access, or run the full checkout path in test mode and enter promotion code CMUXDEV100, a 100%-off forever coupon. Undo either with dev-reset.sh before retesting.

How does cmux determine Pro plan entitlement?▼

Entitlement comes from cmuxPlan in Stack clientReadOnlyMetadata, which is the only field VM code reads. A cmuxVmPlan manual override wins, and resolveProPlanStatus ORs legacy Stack products with active stripe_subscriptions rows.

How is the Stripe webhook kept idempotent and safe?▼

The /api/stripe/webhook route is signature-verified and insert-first idempotent through the stripe_webhook_events table. It only handles events with metadata.app set to cmux, returns 2xx only after durable writes, and returns 500 so Stripe retries on failure.

Why do pages outside the locale tree return 404 in the cmux web app?▼

Pages outside app/[locale] need a proxy.ts bypass, like /app-pricing and /billing, or next-intl rewrites them into the locale tree. Those subtrees also need their own layout with html and body tags.

What is the correct order for running billing database migrations?▼

Run bun run cloud-vm:preflight, then bun run cloud-vm:migrate -- staging, deploy staging, and finally bun run cloud-vm:migrate -- production. Never run migrations from builds.

Related Skills

Explore More Software Engineering Skills→
pedronauckpedronauck
567

stripe-subscriptions

Implement Stripe subscription billing with feature flags, webhooks, and billing portal.

Community
Advanced
abner-magalabner-magal

staging-validation-phase

Guide manual staging validation with smoke tests, user flows, migration checks, and rollback tests.

Community
Advanced
Columbia-Cloudworks-LLCColumbia-Cloudworks-LLC
1

billing-simulator

Simulate Stripe subscription lifecycle events against a local Supabase instance.

Official
Intermediate
Canhada-LabsCanhada-Labs
2

monetization-and-billing

Implement Stripe billing and subscription management for SaaS platforms.

Official
Advanced