Subscription Billing in Next.js: Trials, Upgrades, Cancellations, and Dunning

#saas #nextjs #typescript #stripe

The subscription model is recurring revenue at the cost of recurring complexity. Upgrades, downgrades, trials, cancellations, failed payments -- each scenario needs to work correctly. Here's how to implement it properly.

The State Machine

A subscription has well-defined states. Modeling them explicitly prevents bugs:

type SubscriptionStatus =
  | "none"        // No subscription, free tier
  | "trialing"    // In trial period
  | "active"      // Paying, current
  | "past_due"    // Payment failed, grace period
  | "canceled"    // Canceled, access until period end
  | "expired"     // No access

function hasAccess(user: User): boolean {
  switch (user.subscriptionStatus) {
    case "trialing":
    case "active":
      return true
    case "past_due":
      return true  // Grace period -- still has access
    case "canceled":
      // Has access until the period ends
      return user.stripeCurrentPeriodEnd
        ? user.stripeCurrentPeriodEnd > new Date()
        : false
    case "none":
    case "expired":
    default:
      return false
  }
}

The Database Schema

model User {
  id String @id @default(cuid())
  email String @unique

  // Stripe fields
  stripeCustomerId       String?   @unique
  stripeSubscriptionId   String?   @unique
  stripePriceId          String?
  stripeCurrentPeriodEnd DateTime?
  subscriptionStatus     String    @default("none")

  // Usage
  tokensUsed  Int @default(0)
  tokensLimit Int @default(10000)  // Free tier limit
}

Webhook Handlers: The Core Logic

Every subscription state change comes through a Stripe webhook. Handle each event:

// src/app/api/webhooks/stripe/route.ts

async function handleEvent(event: Stripe.Event) {
  switch (event.type) {
    // Checkout completed (new subscription or upgrade)
    case "checkout.session.completed":
      await handleCheckoutComplete(event.data.object as Stripe.Checkout.Session)
      break

    // Subscription created or updated (covers trials starting)
    case "customer.subscription.created":
    case "customer.subscription.updated":
      await handleSubscriptionUpdate(event.data.object as Stripe.Subscription)
      break

    // Subscription canceled (user hit cancel -- but they keep access until period end)
    case "customer.subscription.deleted":
      await handleSubscriptionCanceled(event.data.object as Stripe.Subscription)
      break

    // Payment failed (move to past_due for grace period)
    case "invoice.payment_failed":
      await handlePaymentFailed(event.data.object as Stripe.Invoice)
      break

    // Payment succeeded (resolves past_due if it was one)
    case "invoice.paid":
      await handlePaymentSucceeded(event.data.object as Stripe.Invoice)
      break
  }
}

async function handleSubscriptionUpdate(sub: Stripe.Subscription) {
  await db.user.update({
    where: { stripeCustomerId: sub.customer as string },
    data: {
      stripeSubscriptionId: sub.id,
      stripePriceId: sub.items.data[0].price.id,
      stripeCurrentPeriodEnd: new Date(sub.current_period_end * 1000),
      subscriptionStatus: sub.status,  // Stripe status maps directly
      tokensLimit: getTokenLimitForPlan(sub.items.data[0].price.id),
    }
  })
}

async function handleSubscriptionCanceled(sub: Stripe.Subscription) {
  // Don't remove access yet -- user paid through current period
  await db.user.update({
    where: { stripeCustomerId: sub.customer as string },
    data: {
      subscriptionStatus: "canceled",
      stripeCurrentPeriodEnd: new Date(sub.current_period_end * 1000),
    }
  })
}

async function handlePaymentFailed(invoice: Stripe.Invoice) {
  await db.user.update({
    where: { stripeCustomerId: invoice.customer as string },
    data: { subscriptionStatus: "past_due" }
  })

  // Send payment failed email
  const user = await db.user.findUnique({
    where: { stripeCustomerId: invoice.customer as string }
  })
  if (user) {
    await sendPaymentFailedEmail(user)
  }
}

function getTokenLimitForPlan(priceId: string): number {
  const limits: Record<string, number> = {
    [process.env.STRIPE_FREE_PRICE_ID!]: 10_000,
    [process.env.STRIPE_PRO_PRICE_ID!]: 500_000,
    [process.env.STRIPE_ENTERPRISE_PRICE_ID!]: 5_000_000,
  }
  return limits[priceId] ?? 10_000
}

The Checkout Flow

// src/app/api/billing/checkout/route.ts
export async function POST(req: NextRequest) {
  const session = await auth()
  if (!session) return NextResponse.json({ error: "Unauthorized" }, { status: 401 })

  const { priceId, trial } = await req.json()

  let customerId = (await db.user.findUnique({
    where: { id: session.user.id },
    select: { stripeCustomerId: true }
  }))?.stripeCustomerId

  if (!customerId) {
    const customer = await stripe.customers.create({
      email: session.user.email!,
      metadata: { userId: session.user.id }
    })
    customerId = customer.id
    await db.user.update({
      where: { id: session.user.id },
      data: { stripeCustomerId: customerId }
    })
  }

  const checkoutSession = await stripe.checkout.sessions.create({
    customer: customerId,
    mode: "subscription",
    payment_method_types: ["card"],
    line_items: [{ price: priceId, quantity: 1 }],
    ...(trial ? { subscription_data: { trial_period_days: 14 } } : {}),
    metadata: { userId: session.user.id },
    success_url: `${process.env.NEXTAUTH_URL}/dashboard?upgraded=true`,
    cancel_url: `${process.env.NEXTAUTH_URL}/pricing`,
    allow_promotion_codes: true,
  })

  return NextResponse.json({ url: checkoutSession.url })
}

Upgrade and Downgrade

// src/app/api/billing/change-plan/route.ts
export async function POST(req: NextRequest) {
  const session = await auth()
  if (!session) return NextResponse.json({ error: "Unauthorized" }, { status: 401 })

  const { newPriceId } = await req.json()
  const user = await db.user.findUnique({ where: { id: session.user.id } })

  if (!user?.stripeSubscriptionId) {
    return NextResponse.json({ error: "No active subscription" }, { status: 400 })
  }

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

  await stripe.subscriptions.update(user.stripeSubscriptionId, {
    items: [{
      id: subscription.items.data[0].id,
      price: newPriceId,
    }],
    proration_behavior: "create_prorations",  // Charge/credit proportionally
  })

  return NextResponse.json({ success: true })
}

The Billing Portal (Free From Stripe)

Don't build cancel/update UI yourself:

// Redirect to Stripe's hosted billing portal
export async function POST(req: NextRequest) {
  const session = await auth()
  const user = await db.user.findUnique({ where: { id: session!.user.id } })

  const portal = await stripe.billingPortal.sessions.create({
    customer: user!.stripeCustomerId!,
    return_url: `${process.env.NEXTAUTH_URL}/dashboard`,
  })

  return NextResponse.json({ url: portal.url })
}