Payment System

Build a billing system on top of Stripe: ## Database Schema model Customer { id String @id @default(cuid()) userId String @unique user User @relation(fields: [userId], references: [id]) stripeCustomerId String @unique email String name String? subscriptions Subscription[] invoices Invoice[] paymentMethods PaymentMethod[] createdAt DateTime @default(now()) updatedAt DateTime @updatedAt } model Subscription { id String @id @default(cuid()) customerId String customer Customer @relation(fields: [customerId], references: [id]) stripeSubscriptionId String @unique stripePriceId String status SubscriptionStatus currentPeriodStart DateTime currentPeriodEnd DateTime cancelAtPeriodEnd Boolean @default(false) canceledAt DateTime? quantity Int @default(1) // Usage-based billing usageRecords UsageRecord[] createdAt DateTime @default(now()) updatedAt DateTime @updatedAt } enum SubscriptionStatus { active past_due canceled unpaid trialing paused } model Invoice { id String @id @default(cuid()) customerId String customer Customer @relation(fields: [customerId], references: [id]) stripeInvoiceId String @unique amountDue Int amountPaid Int currency String status String invoicePdf String? hostedInvoiceUrl String? periodStart DateTime periodEnd DateTime createdAt DateTime @default(now()) } model UsageRecord { id String @id @default(cuid()) subscriptionId String subscription Subscription @relation(fields: [subscriptionId], references: [id]) quantity Int timestamp DateTime action String // 'increment' | 'set' idempotencyKey String @unique createdAt DateTime @default(now()) } ## Webhook Handlers Handle these Stripe events (must be idempotent): checkout.session.completed - Create/update customer record - Create subscription record - Provision access invoice.paid - Update subscription status - Record invoice - Send receipt email invoice.payment_failed - Update subscription to past_due - Trigger dunning email sequence - Schedule retry reminder customer.subscription.updated - Sync status, period, cancel flags - Handle plan changes - Adjust access/limits customer.subscription.deleted - Mark subscription canceled - Revoke access - Trigger win-back flow ## Customer Portal API GET /api/billing/subscription - Return current plan, status, usage, next billing date POST /api/billing/change-plan - Validate new plan is valid upgrade/downgrade - Calculate proration - Call Stripe to update subscription POST /api/billing/cancel - Set cancelAtPeriodEnd = true - Trigger feedback survey - Send confirmation email POST /api/billing/resume - Clear cancelAtPeriodEnd - Send confirmation POST /api/billing/update-payment-method - Create Stripe SetupIntent - Return client secret for frontend ## Usage-Based Billing POST /api/billing/usage - Validate subscription is active - Record usage with idempotency key - Report to Stripe (async, batched) GET /api/billing/usage - Return current period usage - Show projected invoice amount