Stripe Billing Scaffold

About This Skill

# Stripe Billing Scaffold Stop reading 600 pages of Stripe docs. This skill scaffolds a production-ready billing system in one shot — covering the 80% of cases that take 80% of the time. ## What it does Generates and explains the code for: - **Subscriptions** — recurring billing with trials, proration, plan changes - **Metered usage** — pay-per-API-call, storage GB-hour, etc. - **One-time payments** — Checkout Sessions, Payment Intents - **Customer Portal** — self-service plan changes, invoices, payment methods - **Webhooks** — 12 critical events handled with idempotency - **Tax** — Stripe Tax with automatic calculation - **Multi-currency** — present in local currency, settle in your currency - **Coupons / discounts** — first-purchase, recurring, duration - **Invoice customization** — branding, line items, custom fields - **Refunds & disputes** — auto-handle chargebacks - **Fraud** — Radar rules, 3DS, manual review queue - **Reporting** — MRR, churn, LTV, cohort analysis Output: **TypeScript** (Node + Next.js) and **Python** (FastAPI) starter projects, plus a 60-item security checklist. ## When to use it - You're building a SaaS and need to add billing - Your current Stripe integration is buggy and you want a reference - You need to add subscriptions to an existing product - You're launching internationally and need tax + multi-currency - An auditor is asking "how do you handle failed payments?" - You want to meter usage for AI/API products ## Why it's better than ad-hoc prompting Most "integrate Stripe" prompts give toy examples with no error handling. This skill is different: - **Production patterns** — every snippet includes idempotency, retries, error handling - **12 patterns** — covers edge cases most tutorials skip - **TypeScript + Python** — language-agnostic concepts, idiomatic code - **Security checklist** — 60 items (PCI scope, secret rotation, webhook signatures) - **Real edge cases** — failed payments, disputes, plan downgrades mid-cycle ## Architecture ``` ┌─────────────────────────────────────────────────────────┐ │ Agent (Claude/Cursor) │ │ - Asks for billing requirements │ │ - Generates code from templates │ │ - Walks through security checklist │ └───────────────┬─────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────┐ │ skills/stripe-billing-scaffold/ │ │ scripts/ │ │ ├── scaffold.py # Generate starter project │ │ ├── webhook_handler.py # Production webhook handler │ │ ├── metered_usage.py # Track + bill usage │ │ ├── tax_calc.py # Stripe Tax integration │ │ └── check_security.py # 60-item audit │ │ references/ │ │ ├── 12-patterns.md # All patterns explained │ │ ├── webhook-events.md # 12 critical events │ │ ├── subscription-lifecycle.md │ │ ├── metered-usage-guide.md │ │ ├── tax-and-compliance.md │ │ └── security-checklist.md │ │ templates/ │ │ ├── typescript/ # Next.js + Stripe SDK │ │ └── python/ # FastAPI + Stripe SDK │ └─────────────────────────────────────────────────────────┘ ``` ## Quick start ```bash # 1. Install pip install stripe # 2. Generate a starter python scripts/scaffold.py --lang typescript --framework nextjs --out myapp/ python scripts/scaffold.py --lang python --framework fastapi --out myapp/ # 3. Audit your existing integration python scripts/check_security.py ./src/ # 4. Webhook handler ready to copy cp templates/typescript/webhooks/stripe.ts src/app/api/webhooks/stripe/route.ts ``` ## The 12 patterns | # | Pattern | Use case | |---|---------|----------| | 1 | **Checkout Session** | Hosted payment page (one-time) | | 2 | **Subscription create** | Recurring plans with trial | | 3 | **Metered usage** | Pay per API call / GB / hour | | 4 | **Plan upgrade/downgrade** | Mid-cycle, with proration | | 5 | **Customer Portal** | Self-service plan mgmt | | 6 | **Webhook handler** | 12 events, idempotent, retried | | 7 | **Stripe Tax** | Auto-calc + collect per region | | 8 | **Multi-currency** | Show local, settle in USD | | 9 | **Coupon engine** | First-purchase, % off, fixed off | | 10 | **Dunning** | Smart Retries, recovery emails | | 11 | **Refund / dispute** | Auto-respond to chargebacks | | 12 | **Revenue recognition** | For SaaS metrics + accounting | ## The 60-item security checklist (top items) - [ ] API keys in env vars, never in code - [ ] Webhook signature verification on every event - [ ] Idempotency keys on all POST requests - [ ] Restricted API keys (different per service) - [ ] PCI scope: never touch card data directly - [ ] HTTPS only, HSTS, secure cookies - [ ] 3DS for high-risk transactions - [ ] Webhook handler is idempotent (event ID dedup) - [ ] Webhook handler returns 2xx within 5s - [ ] Long work moved to background queue - [ ] Failed payments trigger dunning workflow - [ ] Stripe Radar enabled with custom rules - [ ] Test mode keys never in production - [ ] Secret rotation every 90 days - [ ] Audit log all financial operations - ...50 more ## Pricing Single-purchase, lifetime access. $15.00. Includes: - 5 Python scripts (scaffold, webhook, metered, tax, security audit) - 6 reference docs (12 patterns, webhooks, lifecycle, metered, tax, security) - 2 starter projects (TypeScript Next.js + Python FastAPI) - 60-item security checklist - Future updates for the same major version ## Example usage > "I have a Next.js SaaS. Add subscriptions with a 14-day trial and metered API usage. Use Stripe Tax for EU customers." The skill will: 1. Generate the Next.js route handlers (`/api/checkout`, `/api/webhooks/stripe`, `/api/portal`) 2. Generate the database schema (users, subscriptions, usage_records) 3. Generate the customer portal link 4. Configure Stripe Tax 5. Output a `STRIPE_SETUP.md` walkthrough ## Compatibility Works with any agent that supports the SKILL.md standard and can execute Python: Claude Code, OpenClaw, Codex CLI, Cursor, Gemini CLI, Cline, Windsurf, Aider. Code is framework-agnostic; reference implementations for Next.js + FastAPI included. Tested on Linux, macOS, Windows. ## Tags stripe, billing, payments, subscriptions, saas, fintech, backend, ecommerce