Documentation

Subscription & Billing

Stripe powers the entire paid experience—checkout, customer portal, plan upgrades, downgrades, and webhook driven sync. All logic lives inside src/lib/stripe.ts and the API routes undersrc/app/api/stripe.

What You Get

  • Three production-ready plans (Starter, Foundation, Accelerate) plus a free tier.
  • Pre-wired checkout and billing portal buttons on /dashboard/billing.
  • Webhook handling for subscription creation, updates, cancellations, payment failures, and trials.
  • Feature flags per plan via STRIPE_PLANS in src/lib/stripe.ts.

Setup Checklist

  1. Follow STRIPE_SETUP.md after unzipping the project.
  2. Create the three products + monthly prices in the Stripe Dashboard and collect their IDs.
  3. Update the env vars:
    • STRIPE_SECRET_KEY, NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY
    • Price IDs + (optional) product IDs
    • STRIPE_WEBHOOK_SECRET (from Stripe CLI or Dashboard)
  4. Start stripe listen --forward-to localhost:3000/api/stripe/webhook whenever you runnpm run dev.

Billing API Routes

  • POST /api/stripe/checkout: Creates a checkout session for the selected plan. Called from the dashboard using the logged-in user ID and plan slug.
  • POST /api/stripe/portal: Opens the Stripe customer portal so users can update payment methods, cancel, etc.
  • POST /api/stripe/update-subscription: Switches plans without sending the user back through checkout.
  • POST /api/stripe/webhook: Processes all incoming events and updates Prisma models +User stripe fields.

Plan Configuration

Edit STRIPE_PLANS to change descriptions, pricing, trial days, limits, and feature flags. For example:

STRIPE_PLANS.STARTER = {
  ...,
  price: 39,
  features: { apiCalls: 20000, storage: 25, projects: 10, teamMembers: 5 },
  enabledFeatures: { analytics: true, team: false, ... }
};

Enforcing Access

  • Middleware enforcement: set ENABLE_SUBSCRIPTION_ENFORCEMENT="true" to redirect unpaid users away from /dashboard/analytics, /dashboard/projects, and /dashboard/team.
  • Component-level enforcement: import isPlanFeatureEnabled andhasFeatureAccess to hide UI or block actions on a per-feature basis.

Testing Notes

  • Use Stripe test card 4242 4242 4242 4242 with any future expiry/CVC.
  • Cancel, upgrade, and downgrade from the dashboard to confirm webhooks update Prisma.
  • Verify your User records receive stripeCustomerId,stripeSubscriptionId, stripePriceId, and stripeCurrentPeriodEnd.