Usage-Based Billing | Bootspring Docs

Metered billing based on API usage with Stripe.

Dependencies#

npm install stripe

Environment Variables#

# .env.local
STRIPE_SECRET_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...
STRIPE_METERED_PRICE_ID=price_metered_...

Database Schema#

// prisma/schema.prisma
model User {
  id                String   @id @default(cuid())
  clerkId           String   @unique
  email             String   @unique

  // Stripe
  stripeCustomerId  String?  @unique
  subscriptionId    String?
  subscriptionItemId String? // For metered billing

  // Usage tracking
  usageRecords      UsageRecord[]

  createdAt         DateTime @default(now())
  updatedAt         DateTime @updatedAt
}

model UsageRecord {
  id        String   @id @default(cuid())
  userId    String
  user      User     @relation(fields: [userId], references: [id])

  type      String   // api_call, storage, compute, etc.
  quantity  Int
  metadata  Json?

  timestamp DateTime @default(now())

  // Stripe sync
  reportedToStripe Boolean @default(false)
  stripeRecordId   String?

  @@index([userId, type, timestamp])
  @@index([reportedToStripe])
}

Create Metered Subscription#

// app/api/subscriptions/metered/route.ts
import { auth } from '@clerk/nextjs/server';
import { NextRequest, NextResponse } from 'next/server';
import { stripe } from '@/lib/stripe';
import { prisma } from '@/lib/prisma';

export async function POST(request: NextRequest) {
  const { userId } = await auth();
  if (!userId) {
    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
  }

  const user = await prisma.user.findUnique({
    where: { clerkId: userId },
  });

  if (!user) {
    return NextResponse.json({ error: 'User not found' }, { status: 404 });
  }

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

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

  // Create subscription with metered price
  const subscription = await stripe.subscriptions.create({
    customer: customerId,
    items: [
      {
        price: process.env.STRIPE_METERED_PRICE_ID,
      },
    ],
    payment_behavior: 'default_incomplete',
    expand: ['latest_invoice.payment_intent'],
  });

  // Save subscription item ID for reporting usage
  const subscriptionItemId = subscription.items.data[0].id;

  await prisma.user.update({
    where: { id: user.id },
    data: {
      stripeCustomerId: customerId,
      subscriptionId: subscription.id,
      subscriptionItemId,
    },
  });

  return NextResponse.json({
    subscriptionId: subscription.id,
    clientSecret: (subscription.latest_invoice as any)?.payment_intent?.client_secret,
  });
}

Usage Tracking Service#

// lib/services/usage-service.ts
import { prisma } from '@/lib/prisma';
import { stripe } from '@/lib/stripe';

export type UsageType = 'api_call' | 'storage_gb' | 'compute_minutes';

export async function recordUsage(
  userId: string,
  type: UsageType,
  quantity: number,
  metadata?: Record<string, any>
) {
  // Record locally first
  const record = await prisma.usageRecord.create({
    data: {
      userId,
      type,
      quantity,
      metadata,
    },
  });

  return record;
}

export async function getUsageSummary(userId: string, period: 'day' | 'month') {
  const startDate = new Date();

  if (period === 'day') {
    startDate.setHours(0, 0, 0, 0);
  } else {
    startDate.setDate(1);
    startDate.setHours(0, 0, 0, 0);
  }

  const records = await prisma.usageRecord.groupBy({
    by: ['type'],
    where: {
      userId,
      timestamp: { gte: startDate },
    },
    _sum: {
      quantity: true,
    },
  });

  return records.reduce(
    (acc, record) => ({
      ...acc,
      [record.type]: record._sum.quantity || 0,
    }),
    {} as Record<UsageType, number>
  );
}

export async function reportUsageToStripe() {
  // Get unreported usage records
  const records = await prisma.usageRecord.findMany({
    where: { reportedToStripe: false },
    include: { user: true },
    orderBy: { timestamp: 'asc' },
    take: 1000,
  });

  // Group by user
  const byUser = records.reduce(
    (acc, record) => {
      const key = record.userId;
      if (!acc[key]) {
        acc[key] = {
          user: record.user,
          records: [],
          total: 0,
        };
      }
      acc[key].records.push(record);
      acc[key].total += record.quantity;
      return acc;
    },
    {} as Record<string, { user: any; records: any[]; total: number }>
  );

  // Report to Stripe
  for (const [userId, data] of Object.entries(byUser)) {
    if (!data.user.subscriptionItemId) {
      continue;
    }

    try {
      // Create usage record in Stripe
      const stripeRecord = await stripe.subscriptionItems.createUsageRecord(
        data.user.subscriptionItemId,
        {
          quantity: data.total,
          timestamp: 'now',
          action: 'increment',
        }
      );

      // Mark as reported
      await prisma.usageRecord.updateMany({
        where: {
          id: { in: data.records.map((r) => r.id) },
        },
        data: {
          reportedToStripe: true,
          stripeRecordId: stripeRecord.id,
        },
      });
    } catch (error) {
      console.error(`Failed to report usage for user ${userId}:`, error);
    }
  }
}

API Usage Middleware#

// lib/middleware/track-usage.ts
import { NextRequest, NextResponse } from 'next/server';
import { recordUsage } from '@/lib/services/usage-service';

export function withUsageTracking(
  handler: (req: NextRequest, ctx: any) => Promise<Response>
) {
  return async (req: NextRequest, ctx: any) => {
    const startTime = Date.now();

    // Execute the handler
    const response = await handler(req, ctx);

    // Track usage
    const userId = ctx.user?.id;
    if (userId) {
      const duration = Date.now() - startTime;

      await recordUsage(userId, 'api_call', 1, {
        endpoint: req.nextUrl.pathname,
        method: req.method,
        status: response.status,
        duration,
      });
    }

    return response;
  };
}

Cron Job for Stripe Reporting#

// app/api/cron/report-usage/route.ts
import { NextRequest, NextResponse } from 'next/server';
import { reportUsageToStripe } from '@/lib/services/usage-service';

export async function POST(request: NextRequest) {
  // Verify cron secret
  const authHeader = request.headers.get('authorization');
  if (authHeader !== `Bearer ${process.env.CRON_SECRET}`) {
    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
  }

  try {
    await reportUsageToStripe();
    return NextResponse.json({ success: true });
  } catch (error) {
    console.error('Usage reporting failed:', error);
    return NextResponse.json({ error: 'Failed' }, { status: 500 });
  }
}

// vercel.json
{
  "crons": [
    {
      "path": "/api/cron/report-usage",
      "schedule": "0 * * * *"
    }
  ]
}

Usage Dashboard Component#

// components/UsageDashboard.tsx
'use client';

import { useState, useEffect } from 'react';
import { BarChart, Activity, Database, Cpu } from 'lucide-react';

interface UsageData {
  api_call: number;
  storage_gb: number;
  compute_minutes: number;
}

interface UsageLimit {
  api_call: number;
  storage_gb: number;
  compute_minutes: number;
}

export function UsageDashboard() {
  const [usage, setUsage] = useState<UsageData | null>(null);
  const [limits, setLimits] = useState<UsageLimit | null>(null);

  useEffect(() => {
    fetch('/api/usage')
      .then((res) => res.json())
      .then((data) => {
        setUsage(data.usage);
        setLimits(data.limits);
      });
  }, []);

  if (!usage || !limits) {
    return <div>Loading...</div>;
  }

  const metrics = [
    {
      name: 'API Calls',
      icon: Activity,
      current: usage.api_call,
      limit: limits.api_call,
      unit: 'calls',
    },
    {
      name: 'Storage',
      icon: Database,
      current: usage.storage_gb,
      limit: limits.storage_gb,
      unit: 'GB',
    },
    {
      name: 'Compute',
      icon: Cpu,
      current: usage.compute_minutes,
      limit: limits.compute_minutes,
      unit: 'minutes',
    },
  ];

  return (
    <div className="space-y-6">
      <h2 className="text-xl font-semibold">Usage This Month</h2>

      <div className="grid md:grid-cols-3 gap-6">
        {metrics.map((metric) => {
          const percentage = (metric.current / metric.limit) * 100;
          const isWarning = percentage > 80;
          const isDanger = percentage > 95;

          return (
            <div
              key={metric.name}
              className="p-6 bg-white dark:bg-gray-900 rounded-xl border"
            >
              <div className="flex items-center gap-3 mb-4">
                <metric.icon className="w-5 h-5 text-gray-500" />
                <span className="font-medium">{metric.name}</span>
              </div>

              <div className="text-3xl font-bold mb-2">
                {metric.current.toLocaleString()}
                <span className="text-sm font-normal text-gray-500 ml-1">
                  / {metric.limit.toLocaleString()} {metric.unit}
                </span>
              </div>

              <div className="h-2 bg-gray-200 dark:bg-gray-700 rounded-full overflow-hidden">
                <div
                  className={`h-full rounded-full transition-all ${
                    isDanger
                      ? 'bg-red-500'
                      : isWarning
                        ? 'bg-yellow-500'
                        : 'bg-green-500'
                  }`}
                  style={{ width: `${Math.min(percentage, 100)}%` }}
                />
              </div>

              <p className="text-sm text-gray-500 mt-2">
                {percentage.toFixed(1)}% used
              </p>
            </div>
          );
        })}
      </div>
    </div>
  );
}

Usage API Route#

// app/api/usage/route.ts
import { auth } from '@clerk/nextjs/server';
import { NextResponse } from 'next/server';
import { getUsageSummary } from '@/lib/services/usage-service';
import { getUserSubscription } from '@/lib/subscription';

export async function GET() {
  const { userId } = await auth();
  if (!userId) {
    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
  }

  const [usage, subscription] = await Promise.all([
    getUsageSummary(userId, 'month'),
    getUserSubscription(userId),
  ]);

  return NextResponse.json({
    usage,
    limits: subscription?.limits || {
      api_call: 1000,
      storage_gb: 5,
      compute_minutes: 60,
    },
  });
}

Pricing Configuration#

// lib/pricing.ts
export const USAGE_PRICING = {
  api_call: {
    name: 'API Calls',
    tiers: [
      { upTo: 10000, pricePerUnit: 0 }, // Free tier
      { upTo: 100000, pricePerUnit: 0.0001 }, // $0.10 per 1000
      { upTo: 1000000, pricePerUnit: 0.00005 }, // $0.05 per 1000
      { upTo: null, pricePerUnit: 0.00002 }, // $0.02 per 1000
    ],
  },
  storage_gb: {
    name: 'Storage',
    tiers: [
      { upTo: 5, pricePerUnit: 0 }, // 5GB free
      { upTo: null, pricePerUnit: 0.10 }, // $0.10 per GB
    ],
  },
  compute_minutes: {
    name: 'Compute',
    tiers: [
      { upTo: 60, pricePerUnit: 0 }, // 60 min free
      { upTo: null, pricePerUnit: 0.01 }, // $0.01 per minute
    ],
  },
};

export function calculateCost(
  type: keyof typeof USAGE_PRICING,
  quantity: number
): number {
  const pricing = USAGE_PRICING[type];
  let remaining = quantity;
  let cost = 0;
  let previousLimit = 0;

  for (const tier of pricing.tiers) {
    const tierLimit = tier.upTo ?? Infinity;
    const tierQuantity = Math.min(remaining, tierLimit - previousLimit);

    if (tierQuantity > 0) {
      cost += tierQuantity * tier.pricePerUnit;
      remaining -= tierQuantity;
    }

    previousLimit = tierLimit;
    if (remaining <= 0) break;
  }

  return cost;
}