🎨 Vibe Coding Kit

You are building a production-grade billing and subscription management system for a SaaS platform. This system sits on TOP of Stripe (you do not replace Stripe), handling business logic, user experience, and custom billing workflows. CORE RESPONSIBILITIES: 1. Subscription Management - Create, update, cancel subscriptions tied to Stripe subscription objects - Handle plan changes (upgrades/downgrades, prorations) - Track billing cycles, renewal dates, and trial periods - Support annual, monthly, and custom billing intervals 2. Usage-Based Billing - Accept metered usage events from your application - Aggregate usage per billing cycle - Sync aggregated usage to Stripe for prorated charges - Support tiered pricing (e.g., $0.10 per unit for first 1000, $0.08 after) - Real-time usage dashboards for customers 3. Customer Billing Portal - Self-serve dashboard showing current plan, usage, and costs - Ability to upgrade/downgrade plans - Manage payment methods - View invoice history and download PDFs - Usage breakdown by feature/dimension - Billing settings (email, tax ID, address) 4. Invoice & Billing Management - Generate branded invoices (PDF with company logo, terms, tax info) - Send invoice emails automatically after payment success - Custom invoice numbering and metadata - Support tax rates/GST/VAT (country-specific) - Partial refunds and credit memos - Line-item detail matching customer's actual usage 5. Webhook Handling & Sync - Listen to Stripe webhooks: invoice.payment_succeeded, invoice.payment_failed, customer.subscription.deleted, charge.refunded - Update local database to reflect Stripe state (invoice status, subscription status) - Handle race conditions (webhook arrives before API call returns) - Retry failed webhook processing with exponential backoff - Webhook signature verification (Stripe-Signature header) 6. Dunning & Failed Payment Recovery - Track payment failures and retry attempts - Send reminder emails after failed payment (Day 1, Day 4, Day 7) - Auto-retry failed payments using Stripe's retry rules - Pause/downgrade service gracefully if dunning exhausted - Offer payment method update flow before service suspension - Log all dunning actions for troubleshooting 7. Reporting & Analytics - MRR (Monthly Recurring Revenue) by plan/customer - Churn rate and reasons (voluntary, payment failure, etc.) - LTV (Lifetime Value) calculation - Expansion revenue (upgrades, additional products) - Customer segmentation (by plan, usage, region) - Cohort analysis for retention TECH STACK: - Framework: Next.js with App Router (TypeScript) - Database: PostgreSQL with Prisma ORM - Payment Processor: Stripe API (Python SDK or Node SDK) - Job Queue: Bull (Redis backend) for async tasks - Auth: NextAuth.js for customer accounts - Email: Resend for transactional emails - API: RESTful endpoints at /api/billing/* DATABASE SCHEMA (Prisma): ``` model Customer { id String @id @default(cuid()) userId String @unique stripeCustomerId String @unique email String name String createdAt DateTime @default(now()) subscriptions Subscription[] invoices Invoice[] usageEvents UsageEvent[] } model Subscription { id String @id @default(cuid()) customerId String customer Customer @relation(fields: [customerId], references: [id]) stripeSubscriptionId String @unique planId String status String // active, past_due, canceled, unpaid currentPeriodStart DateTime currentPeriodEnd DateTime canceledAt DateTime? trialEndsAt DateTime? createdAt DateTime @default(now()) invoices Invoice[] } model Invoice { id String @id @default(cuid()) customerId String customer Customer @relation(fields: [customerId], references: [id]) stripeInvoiceId String @unique subscriptionId String subscription Subscription @relation(fields: [subscriptionId], references: [id]) status String // draft, open, paid, void, uncollectible amount Int currency String paidAt DateTime? failedAt DateTime? dueDate DateTime createdAt DateTime @default(now()) } model UsageEvent { id String @id @default(cuid()) customerId String customer Customer @relation(fields: [customerId], references: [id]) dimension String // "seats", "requests", "storage_gb" quantity Float timestamp DateTime @default(now()) @@index([customerId, dimension, timestamp]) } ``` KEY ENDPOINTS: - POST /api/billing/subscriptions - Create subscription (after Stripe charges succeeds) - GET /api/billing/subscriptions/:id - Get subscription details - POST /api/billing/subscriptions/:id/upgrade - Change plan - POST /api/billing/subscriptions/:id/cancel - Cancel subscription - POST /api/billing/usage - Track usage event (internal API) - GET /api/billing/invoices - List invoices for customer - GET /api/billing/portal-session - Generate Stripe Billing Portal link - POST /api/billing/webhooks/stripe - Stripe webhook receiver WEBHOOK PROCESSING: - Validate Stripe signature on every webhook - Parse event type and data - Atomically update database (subscription status, invoice state, etc.) - Send confirmation emails (invoice paid, subscription canceled, etc.) - Log all events for audit trail - Return 200 immediately; do heavy lifting asynchronously with Bull jobs DUNNING WORKFLOW: 1. Invoice payment fails → Set invoice.status = "open" 2. Wait 1 day → Send first reminder email 3. Day 4: Auto-retry via Stripe 4. If still failed: Send second reminder + payment method update link 5. Day 7: Final notice + offer to downgrade/pause 6. Day 10: Suspend service/downgrade plan ERROR HANDLING: - Catch Stripe API errors (rate limits, invalid params, auth failures) - Log errors with context (customer ID, subscription ID, attempted action) - Retry transient failures (network timeouts, 500s) with exponential backoff - Alert on critical failures (webhook processing errors, sync issues) - Provide clear error messages to users (e.g., "Payment method declined. Update here.") TESTING: - Unit tests for business logic (proration math, dunning rules, usage aggregation) - Integration tests against Stripe test mode - End-to-end tests for subscription lifecycle (create → upgrade → cancel) - Webhook testing using Stripe CLI - Load testing for metered event ingestion (simulate high-volume customers) This system will be production-ready, scalable to thousands of customers, and fully compliant with Stripe's best practices. Focus on data consistency, error resilience, and delightful customer experience.