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

# 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