Subscription Patterns | Bootspring Docs

Manage recurring billing with Stripe Subscriptions.

Overview#

Subscriptions power SaaS businesses. This pattern covers:

Subscription plan configuration
Creating subscriptions
Plan changes and upgrades
Cancellation and reactivation
Usage limits based on plan

Prerequisites#

npm install stripe

Define Subscription Plans#

Configure your pricing tiers.

// lib/plans.ts
export const PLANS = {
  free: {
    name: 'Free',
    priceId: null,
    limits: {
      projects: 1,
      storage: 100, // MB
      teamMembers: 1,
      apiCalls: 1000
    }
  },
  pro: {
    name: 'Pro',
    priceId: process.env.STRIPE_PRO_PRICE_ID!,
    limits: {
      projects: 10,
      storage: 5000,
      teamMembers: 5,
      apiCalls: 50000
    }
  },
  enterprise: {
    name: 'Enterprise',
    priceId: process.env.STRIPE_ENTERPRISE_PRICE_ID!,
    limits: {
      projects: -1, // unlimited
      storage: -1,
      teamMembers: -1,
      apiCalls: -1
    }
  }
} as const

export type PlanId = keyof typeof PLANS
export type Plan = typeof PLANS[PlanId]

Create Subscription#

Subscribe a user to a plan.

// lib/billing.ts
import { stripe } from '@/lib/stripe'
import { prisma } from '@/lib/db'
import { PLANS, PlanId } from './plans'

export async function createSubscription(userId: string, planId: PlanId) {
  const user = await prisma.user.findUnique({
    where: { id: userId },
    include: { subscription: true }
  })

  if (!user) throw new Error('User not found')

  const plan = PLANS[planId]
  if (!plan.priceId) throw new Error('Cannot subscribe to free plan')

  // Get or create Stripe customer
  let customerId = user.stripeCustomerId

  if (!customerId) {
    const customer = await stripe.customers.create({
      email: user.email,
      metadata: { userId: user.id }
    })
    customerId = customer.id

    await prisma.user.update({
      where: { id: userId },
      data: { stripeCustomerId: customerId }
    })
  }

  // Create checkout session for subscription
  const session = await stripe.checkout.sessions.create({
    customer: customerId,
    mode: 'subscription',
    payment_method_types: ['card'],
    line_items: [{ price: plan.priceId, quantity: 1 }],
    success_url: `${process.env.NEXT_PUBLIC_URL}/billing?success=true`,
    cancel_url: `${process.env.NEXT_PUBLIC_URL}/billing?canceled=true`,
    metadata: { userId, planId }
  })

  return session.url
}

Webhook Handler#

Process subscription events from Stripe.

// app/api/webhooks/stripe/route.ts
import { stripe } from '@/lib/stripe'
import { prisma } from '@/lib/db'
import { headers } from 'next/headers'
import Stripe from 'stripe'

export async function POST(request: Request) {
  const body = await request.text()
  const signature = headers().get('stripe-signature')!

  let event: Stripe.Event

  try {
    event = stripe.webhooks.constructEvent(
      body,
      signature,
      process.env.STRIPE_WEBHOOK_SECRET!
    )
  } catch (err) {
    return Response.json({ error: 'Invalid signature' }, { status: 400 })
  }

  switch (event.type) {
    case 'customer.subscription.created':
    case 'customer.subscription.updated':
      await handleSubscriptionChange(event.data.object as Stripe.Subscription)
      break

    case 'customer.subscription.deleted':
      await handleSubscriptionCanceled(event.data.object as Stripe.Subscription)
      break

    case 'invoice.payment_failed':
      await handlePaymentFailed(event.data.object as Stripe.Invoice)
      break
  }

  return Response.json({ received: true })
}

async function handleSubscriptionChange(subscription: Stripe.Subscription) {
  const customerId = subscription.customer as string

  const user = await prisma.user.findFirst({
    where: { stripeCustomerId: customerId }
  })

  if (!user) return

  await prisma.subscription.upsert({
    where: { userId: user.id },
    create: {
      userId: user.id,
      stripeSubscriptionId: subscription.id,
      stripePriceId: subscription.items.data[0].price.id,
      status: subscription.status,
      currentPeriodEnd: new Date(subscription.current_period_end * 1000)
    },
    update: {
      stripeSubscriptionId: subscription.id,
      stripePriceId: subscription.items.data[0].price.id,
      status: subscription.status,
      currentPeriodEnd: new Date(subscription.current_period_end * 1000)
    }
  })
}

async function handleSubscriptionCanceled(subscription: Stripe.Subscription) {
  const customerId = subscription.customer as string

  const user = await prisma.user.findFirst({
    where: { stripeCustomerId: customerId }
  })

  if (!user) return

  await prisma.subscription.update({
    where: { userId: user.id },
    data: { status: 'canceled' }
  })
}

Get User Plan#

Determine a user's current plan.

// lib/billing.ts
export async function getUserPlan(userId: string): Promise<PlanId> {
  const subscription = await prisma.subscription.findUnique({
    where: { userId }
  })

  if (!subscription || subscription.status !== 'active') {
    return 'free'
  }

  // Find plan by price ID
  for (const [planId, plan] of Object.entries(PLANS)) {
    if (plan.priceId === subscription.stripePriceId) {
      return planId as PlanId
    }
  }

  return 'free'
}

export async function checkLimit(
  userId: string,
  resource: keyof typeof PLANS.free.limits,
  currentCount: number
): Promise<boolean> {
  const planId = await getUserPlan(userId)
  const limit = PLANS[planId].limits[resource]

  // -1 means unlimited
  if (limit === -1) return true

  return currentCount < limit
}

Cancel Subscription#

Cancel at period end or immediately.

// lib/billing.ts
export async function cancelSubscription(
  userId: string,
  immediate: boolean = false
) {
  const subscription = await prisma.subscription.findUnique({
    where: { userId }
  })

  if (!subscription?.stripeSubscriptionId) {
    throw new Error('No active subscription')
  }

  if (immediate) {
    await stripe.subscriptions.cancel(subscription.stripeSubscriptionId)
  } else {
    // Cancel at period end (user keeps access until then)
    await stripe.subscriptions.update(subscription.stripeSubscriptionId, {
      cancel_at_period_end: true
    })
  }

  await prisma.subscription.update({
    where: { userId },
    data: { cancelAtPeriodEnd: !immediate }
  })
}

export async function reactivateSubscription(userId: string) {
  const subscription = await prisma.subscription.findUnique({
    where: { userId }
  })

  if (!subscription?.stripeSubscriptionId) {
    throw new Error('No subscription found')
  }

  await stripe.subscriptions.update(subscription.stripeSubscriptionId, {
    cancel_at_period_end: false
  })

  await prisma.subscription.update({
    where: { userId },
    data: { cancelAtPeriodEnd: false }
  })
}

Change Plan#

Upgrade or downgrade subscription.

// lib/billing.ts
export async function changePlan(userId: string, newPlanId: PlanId) {
  const subscription = await prisma.subscription.findUnique({
    where: { userId }
  })

  if (!subscription?.stripeSubscriptionId) {
    throw new Error('No active subscription')
  }

  const newPlan = PLANS[newPlanId]
  if (!newPlan.priceId) {
    throw new Error('Cannot switch to free plan, cancel instead')
  }

  const stripeSubscription = await stripe.subscriptions.retrieve(
    subscription.stripeSubscriptionId
  )

  await stripe.subscriptions.update(subscription.stripeSubscriptionId, {
    items: [{
      id: stripeSubscription.items.data[0].id,
      price: newPlan.priceId
    }],
    proration_behavior: 'create_prorations'
  })
}

Subscription Status Component#

Display subscription status to users.

// components/billing/SubscriptionStatus.tsx
import { getUserPlan } from '@/lib/billing'
import { prisma } from '@/lib/db'
import { PLANS } from '@/lib/plans'
import { format } from 'date-fns'

export async function SubscriptionStatus({ userId }: { userId: string }) {
  const planId = await getUserPlan(userId)
  const plan = PLANS[planId]

  const subscription = await prisma.subscription.findUnique({
    where: { userId }
  })

  return (
    <div className="rounded-lg border p-6">
      <div className="mb-4 flex items-center justify-between">
        <div>
          <p className="text-sm text-gray-500">Current Plan</p>
          <p className="text-xl font-bold">{plan.name}</p>
        </div>
        {subscription?.status === 'active' && (
          <span className="rounded-full bg-green-100 px-3 py-1 text-sm text-green-800">
            Active
          </span>
        )}
      </div>

      {subscription?.currentPeriodEnd && (
        <p className="text-sm text-gray-600">
          {subscription.cancelAtPeriodEnd
            ? `Access until ${format(subscription.currentPeriodEnd, 'MMM d, yyyy')}`
            : `Renews on ${format(subscription.currentPeriodEnd, 'MMM d, yyyy')}`}
        </p>
      )}
    </div>
  )
}

Best Practices#

Always use webhooks - Don't rely on redirect success URLs
Handle failed payments - Send dunning emails, pause access gracefully
Prorate plan changes - Use Stripe's proration for fair billing
Grace periods - Give users time to update payment methods
Clear plan limits - Show users what they can do on each plan

Stripe - Stripe setup
Webhooks - Webhook handling
Usage Billing - Metered billing