Stripe Subscription Engine

Billing is the part of your SaaS that has to be perfect — and it is the part most likely to be quietly broken. Stripe Subscription Engine turns your AI agent into a senior payments engineer that scaffolds a complete, production-grade subscription system end to end: Checkout, the customer portal, idempotent webhooks, plan and seat management, proration, and dunning — all wired to your database with the edge cases already handled.

The Problem

Every SaaS needs subscription billing, and almost every hand-rolled implementation is subtly wrong. The happy path (a customer subscribes) is easy. The money-losing parts are everything else: a webhook that fires twice and double-charges, a checkout.session.completed you trusted before the invoice was paid, a downgrade that forgets to prorate, a failed renewal that never triggers a dunning email so the customer silently churns, a subscription whose state drifts out of sync with your database after a Stripe-side change. These bugs do not crash — they leak revenue and erode trust, and you usually find them in a support ticket.

What It Does

Stripe Subscription Engine scaffolds the entire billing layer with production hardening built in:

1. Checkout & Portal — Generates the Checkout Session flow for new subscriptions and wires up the Stripe Customer Portal so users can upgrade, downgrade, update cards, and cancel without you building any UI.
2. Hardened Webhooks — Builds a signature-verified, idempotent webhook handler that processes every subscription lifecycle event exactly once, with replay safety and an event log.
3. Plans, Seats & Proration — Implements tiered plans, per-seat billing, mid-cycle upgrades/downgrades, and correct proration so customers are always charged the right amount.
4. Dunning & Recovery — Handles failed payments with retry logic, customer notifications, and a grace period so a declined card does not become silent churn.
5. Source-of-Truth Sync — Generates the database schema and reconciliation logic that keeps your local subscription state perfectly in sync with Stripe, even after out-of-band changes.

Why Use This Skill

Billing is the highest-stakes, lowest-tolerance code in your product: a bug here charges real customers real money. This skill encodes the patterns payments teams learn the hard way — idempotency keys, webhook-driven state, never trusting the client, reconciliation over assumption — into a complete scaffold your agent generates in minutes instead of the week it takes to get right by hand. It pays for itself the first time it prevents a single double-charge or a month of silent churn.

Supported Stacks

Frameworks: Next.js (App Router, default), Remix, SvelteKit, Express, NestJS, and most Node/TypeScript backends. Database/ORM: Postgres with Prisma (default), Drizzle, or raw SQL; adaptable to MySQL. Payments: Stripe Billing (Checkout, Customer Portal, Webhooks, the Subscriptions API).

Use Cases

Launch billing for a new SaaS in a day instead of a week, with the edge cases already covered. Replace a fragile hand-rolled Stripe integration with a hardened, idempotent one. Add per-seat or tiered plans and correct proration to an existing product. Stop revenue leakage from failed-payment churn with built-in dunning.

Known Limitations

You bring your own Stripe account and set your product/price IDs; the skill generates the integration and placeholders, not your Stripe catalog. Tax (Stripe Tax) and complex usage-based metered billing are scaffolded as optional extension points rather than fully configured, since they depend on your jurisdiction and metering model. The skill never handles live card data directly — all card entry happens in Stripe-hosted Checkout and Portal, by design.