Usage-Based Billing Patterns | Bootspring Docs

Implement metered billing with Stripe for pay-as-you-go pricing.

Overview#

Usage-based billing charges customers based on consumption. This pattern covers:

Recording usage with Stripe
Usage tracking in your database
Usage limits and enforcement
Usage dashboard components
Billing cycle management

Prerequisites#

npm install stripe

Record Usage#

Send usage records to Stripe for metered billing.

// lib/usage.ts
import { stripe } from '@/lib/stripe'
import { prisma } from '@/lib/db'

export async function recordUsage(
  userId: string,
  metric: string,
  quantity: number
) {
  // Get subscription with metered price
  const subscription = await prisma.subscription.findUnique({
    where: { userId },
    include: { user: true }
  })

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

  // Find the metered subscription item
  const stripeSubscription = await stripe.subscriptions.retrieve(
    subscription.stripeSubscriptionId
  )

  const meteredItem = stripeSubscription.items.data.find(
    item => item.price.recurring?.usage_type === 'metered'
  )

  if (!meteredItem) {
    throw new Error('No metered subscription item found')
  }

  // Record usage with Stripe
  await stripe.subscriptionItems.createUsageRecord(meteredItem.id, {
    quantity,
    timestamp: Math.floor(Date.now() / 1000),
    action: 'increment'
  })

  // Also store locally for quick access
  await prisma.usageRecord.create({
    data: {
      userId,
      metric,
      quantity,
      timestamp: new Date()
    }
  })
}

Usage Tracking Middleware#

Track API usage automatically.

// lib/usage-middleware.ts
import { prisma } from '@/lib/db'

export async function trackApiUsage(userId: string, endpoint: string) {
  // Buffer usage records for batch processing
  await prisma.usageBuffer.create({
    data: {
      userId,
      metric: 'api_calls',
      endpoint,
      timestamp: new Date()
    }
  })
}

// Background job to flush usage to Stripe (run every minute)
export async function flushUsageToStripe() {
  // Group buffered records by user and metric
  const bufferRecords = await prisma.usageBuffer.groupBy({
    by: ['userId', 'metric'],
    _count: { id: true },
    where: { flushedAt: null }
  })

  for (const record of bufferRecords) {
    try {
      await recordUsage(record.userId, record.metric, record._count.id)

      // Mark as flushed
      await prisma.usageBuffer.updateMany({
        where: {
          userId: record.userId,
          metric: record.metric,
          flushedAt: null
        },
        data: { flushedAt: new Date() }
      })
    } catch (error) {
      console.error(`Failed to flush usage for ${record.userId}:`, error)
    }
  }
}

Usage Summary#

Get usage summary for the current billing period.

// lib/usage.ts
import { startOfMonth, endOfMonth } from 'date-fns'

export async function getUsageSummary(
  userId: string,
  period?: { start: Date; end: Date }
) {
  const startDate = period?.start ?? startOfMonth(new Date())
  const endDate = period?.end ?? new Date()

  const usage = await prisma.usageRecord.groupBy({
    by: ['metric'],
    where: {
      userId,
      timestamp: {
        gte: startDate,
        lte: endDate
      }
    },
    _sum: { quantity: true }
  })

  return usage.reduce((acc, record) => {
    acc[record.metric] = record._sum.quantity ?? 0
    return acc
  }, {} as Record<string, number>)
}

export async function getUsageHistory(
  userId: string,
  metric: string,
  days: number = 30
) {
  const startDate = new Date()
  startDate.setDate(startDate.getDate() - days)

  const records = await prisma.usageRecord.findMany({
    where: {
      userId,
      metric,
      timestamp: { gte: startDate }
    },
    orderBy: { timestamp: 'asc' }
  })

  // Group by day
  const byDay = records.reduce((acc, record) => {
    const day = record.timestamp.toISOString().split('T')[0]
    acc[day] = (acc[day] ?? 0) + record.quantity
    return acc
  }, {} as Record<string, number>)

  return byDay
}

Usage Limits#

Define and enforce usage limits per plan.

// lib/usage-limits.ts
import { PLANS, PlanId } from './plans'
import { getUserPlan } from './billing'
import { getUsageSummary } from './usage'

export const USAGE_LIMITS: Record<PlanId, Record<string, number>> = {
  free: {
    api_calls: 1000,
    ai_tokens: 10000,
    storage_mb: 100
  },
  pro: {
    api_calls: 50000,
    ai_tokens: 500000,
    storage_mb: 5000
  },
  enterprise: {
    api_calls: -1, // unlimited
    ai_tokens: -1,
    storage_mb: -1
  }
}

export async function checkUsageLimit(
  userId: string,
  metric: string
): Promise<{ allowed: boolean; current: number; limit: number }> {
  const planId = await getUserPlan(userId)
  const limit = USAGE_LIMITS[planId][metric]

  // Unlimited
  if (limit === -1) {
    return { allowed: true, current: 0, limit: -1 }
  }

  const usage = await getUsageSummary(userId)
  const current = usage[metric] ?? 0

  return {
    allowed: current < limit,
    current,
    limit
  }
}

export async function enforceUsageLimit(userId: string, metric: string) {
  const { allowed, current, limit } = await checkUsageLimit(userId, metric)

  if (!allowed) {
    throw new UsageLimitExceededError(metric, current, limit)
  }
}

export class UsageLimitExceededError extends Error {
  constructor(
    public metric: string,
    public current: number,
    public limit: number
  ) {
    super(`Usage limit exceeded for ${metric}: ${current}/${limit}`)
    this.name = 'UsageLimitExceededError'
  }
}

Usage Dashboard Component#

Display usage metrics to users.

// components/usage/UsageDashboard.tsx
import { getUsageSummary } from '@/lib/usage'
import { USAGE_LIMITS } from '@/lib/usage-limits'
import { getUserPlan } from '@/lib/billing'

interface Props {
  userId: string
}

export async function UsageDashboard({ userId }: Props) {
  const planId = await getUserPlan(userId)
  const usage = await getUsageSummary(userId)
  const limits = USAGE_LIMITS[planId]

  const metrics = [
    { key: 'api_calls', label: 'API Calls', format: (n: number) => n.toLocaleString() },
    { key: 'ai_tokens', label: 'AI Tokens', format: (n: number) => n.toLocaleString() },
    { key: 'storage_mb', label: 'Storage', format: (n: number) => `${n} MB` }
  ]

  return (
    <div className="grid gap-4 md:grid-cols-3">
      {metrics.map(metric => {
        const current = usage[metric.key] ?? 0
        const limit = limits[metric.key]
        const percentage = limit === -1 ? 0 : (current / limit) * 100

        return (
          <div key={metric.key} className="rounded-lg border p-4">
            <h3 className="text-sm font-medium text-gray-600">{metric.label}</h3>
            <p className="mt-1 text-2xl font-bold">
              {metric.format(current)}
              {limit !== -1 && (
                <span className="text-sm font-normal text-gray-500">
                  {' / '}{metric.format(limit)}
                </span>
              )}
              {limit === -1 && (
                <span className="text-sm font-normal text-gray-500">
                  {' / Unlimited'}
                </span>
              )}
            </p>

            {limit !== -1 && (
              <div className="mt-3">
                <div className="h-2 rounded-full bg-gray-200">
                  <div
                    className={`h-2 rounded-full transition-all ${
                      percentage > 90 ? 'bg-red-500' :
                      percentage > 75 ? 'bg-amber-500' : 'bg-green-500'
                    }`}
                    style={{ width: `${Math.min(100, percentage)}%` }}
                  />
                </div>
                <p className="mt-1 text-xs text-gray-500">
                  {percentage.toFixed(1)}% used
                </p>
              </div>
            )}
          </div>
        )
      })}
    </div>
  )
}

Usage API Middleware#

Enforce limits on API routes.

// middleware/usage.ts
import { NextResponse } from 'next/server'
import { auth } from '@/auth'
import { checkUsageLimit, trackApiUsage } from '@/lib/usage'

export async function withUsageLimit(
  request: Request,
  metric: string,
  handler: () => Promise<Response>
) {
  const session = await auth()

  if (!session?.user) {
    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
  }

  const { allowed, current, limit } = await checkUsageLimit(
    session.user.id,
    metric
  )

  if (!allowed) {
    return NextResponse.json(
      {
        error: 'Usage limit exceeded',
        current,
        limit,
        upgradeUrl: '/pricing'
      },
      { status: 429 }
    )
  }

  // Track usage
  await trackApiUsage(session.user.id, request.url)

  return handler()
}

// Usage in API route
export async function POST(request: Request) {
  return withUsageLimit(request, 'api_calls', async () => {
    // Handle request
    return NextResponse.json({ success: true })
  })
}

Best Practices#

Buffer usage records - Batch writes to reduce API calls
Show real-time usage - Keep users informed of consumption
Warn before limits - Send notifications at 80% usage
Graceful degradation - Handle limit exceeded gracefully
Provide upgrade path - Make it easy to increase limits

Subscriptions - Subscription management
Webhooks - Invoice webhooks
Invoicing - Invoice management