Usage-Based Billing

// Create a key with monthly credits
const key = await unkey.keys.createKey({
  apiId: "api_xxx",
  credits: {
    remaining: 10000, // 10,000 API calls included
    refill: {
      interval: "monthly",
      amount: 10000,
    },
  },
});

// Each verification decrements remaining
const { meta, data } = await unkey.keys.verifyKey({ key: userKey });

if (!data.valid && data.code === "USAGE_EXCEEDED") {
  // Prompt user to upgrade or pay for overage
}

// Check remaining credits
console.log(data.credits); // 9,999 after first call

// lib/unkey.ts
import { Unkey } from "@unkey/api";

const unkey = new Unkey({ rootKey: process.env.UNKEY_ROOT_KEY! });

interface CreateBillingKeyOptions {
  customerId: string;
  plan: "starter" | "growth" | "scale";
  stripeCustomerId?: string;
}

const PLAN_CREDITS = {
  starter: 1_000,
  growth: 10_000,
  scale: 100_000,
};

export async function createBillingKey(options: CreateBillingKeyOptions) {
  const credits = PLAN_CREDITS[options.plan];

  // The SDK throws on failure, so any error propagates to the caller.
  const { data } = await unkey.keys.createKey({
    apiId: process.env.UNKEY_API_ID!,
    externalId: options.customerId, // Link to your user/org
    name: `${options.plan} plan`,
    credits: {
      remaining: credits,
      refill: {
        interval: "monthly",
        amount: credits,
      },
    },
    meta: {
      plan: options.plan,
      stripeCustomerId: options.stripeCustomerId,
      createdAt: new Date().toISOString(),
    },
  });

  return data;
}

// app/api/route.ts
import { Unkey } from "@unkey/api";
import { NextResponse } from "next/server";

const unkey = new Unkey({ rootKey: process.env.UNKEY_ROOT_KEY! });

export async function POST(request: Request) {
  const apiKey = request.headers.get("authorization")?.replace("Bearer ", "");

  if (!apiKey) {
    return NextResponse.json({ error: "Missing API key" }, { status: 401 });
  }

  let data;
  try {
    ({ data } = await unkey.keys.verifyKey({ key: apiKey }));
  } catch {
    return NextResponse.json({ error: "Verification failed" }, { status: 500 });
  }

  if (!data.valid) {
    if (data.code === "USAGE_EXCEEDED") {
      return NextResponse.json(
        {
          error: "Usage limit exceeded",
          remaining: 0,
          message: "Please upgrade your plan or wait for monthly reset",
        },
        { status: 402 }, // Payment Required
      );
    }

    return NextResponse.json(
      { error: "Invalid API key", code: data.code },
      { status: 401 },
    );
  }

  // Include usage info in response headers
  const response = NextResponse.json({
    success: true,
    // Your API response...
  });

  response.headers.set("X-Usage-Remaining", (data.credits ?? 0).toString());

  return response;
}

// lib/billing.ts
import Stripe from "stripe";
import { Unkey } from "@unkey/api";

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);
const unkey = new Unkey({ rootKey: process.env.UNKEY_ROOT_KEY! });

// Record overage usage in Stripe
export async function recordOverage(keyId: string, amount: number) {
  // Get the key to find the Stripe customer
  const { data: key } = await unkey.keys.getKey({ keyId });

  if (!key?.meta?.stripeCustomerId) {
    throw new Error("No Stripe customer linked to this key");
  }

  // Find or create a usage-based subscription item
  const subscriptions = await stripe.subscriptions.list({
    customer: key.meta.stripeCustomerId as string,
    status: "active",
  });

  const subscription = subscriptions.data[0];
  if (!subscription) {
    throw new Error("No active subscription");
  }

  // Find the metered price item
  const meteredItem = subscription.items.data.find(
    (item) => item.price.recurring?.usage_type === "metered",
  );

  if (meteredItem) {
    // Report usage to Stripe
    await stripe.subscriptionItems.createUsageRecord(meteredItem.id, {
      quantity: amount,
      timestamp: Math.floor(Date.now() / 1000),
      action: "increment",
    });
  }
}

// Webhook handler for when credits run out
export async function handleUsageExceeded(keyId: string) {
  const { data: key } = await unkey.keys.getKey({ keyId });

  if (key?.meta?.stripeCustomerId) {
    // Option 1: Add overage credits and bill later
    await unkey.keys.updateKey({
      keyId,
      credits: {
        remaining: 1000, // Grant overage allowance
      },
    });

    await recordOverage(keyId, 1000);

    // Option 2: Or just notify and let them upgrade
    // await sendUpgradeEmail(key.meta.email);
  }
}

// app/api/usage/route.ts
import { Unkey } from "@unkey/api";
import { NextResponse } from "next/server";

const unkey = new Unkey({ rootKey: process.env.UNKEY_ROOT_KEY! });

export async function GET(request: Request) {
  const customerId = request.headers.get("x-customer-id");

  if (!customerId) {
    return NextResponse.json({ error: "Missing customer ID" }, { status: 401 });
  }

  // Get all keys for this customer
  const { data } = await unkey.apis.listKeys({
    apiId: process.env.UNKEY_API_ID!,
    externalId: customerId,
  });

  if (!data.length) {
    return NextResponse.json({ error: "No keys found" }, { status: 404 });
  }

  const key = data[0];

  const remaining = key.credits?.remaining ?? 0;
  const limit = key.credits?.refill?.amount ?? 0;

  return NextResponse.json({
    plan: key.meta?.plan ?? "starter",
    usage: {
      remaining,
      limit,
      used: limit - remaining,
      refillInterval: key.credits?.refill?.interval ?? null,
      refillDay: key.credits?.refill?.refillDay ?? null,
    },
  });
}

export async function upgradePlan(
  keyId: string,
  newPlan: "starter" | "growth" | "scale",
) {
  const newCredits = PLAN_CREDITS[newPlan];

  // Get current usage
  const { data: currentKey } = await unkey.keys.getKey({ keyId });
  const currentRemaining = currentKey.credits?.remaining ?? 0;
  const currentRefillAmount = currentKey.credits?.refill?.amount ?? 0;

  // Option 1: Add the difference (pro-rated)
  const creditsToAdd = newCredits - currentRefillAmount;

  await unkey.keys.updateKey({
    keyId,
    credits: {
      remaining: currentRemaining + creditsToAdd,
      refill: {
        interval: "monthly",
        amount: newCredits,
      },
    },
    meta: {
      ...currentKey.meta,
      plan: newPlan,
      upgradedAt: new Date().toISOString(),
    },
  });

  // Option 2: Reset to new plan's full credits
  // await unkey.keys.updateKey({
  //   keyId,
  //   credits: {
  //     remaining: newCredits,
  //     refill: { interval: "monthly", amount: newCredits },
  //   },
  // });
}

// Create a key with multiple rate limits as credit pools
const { data } = await unkey.keys.createKey({
  apiId: process.env.UNKEY_API_ID!,
  externalId: customerId,
  credits: {
    remaining: 10000, // General API calls
  },
  ratelimits: [
    { name: "ai-tokens", limit: 100000, duration: 2592000000 }, // 30 days
    { name: "storage-mb", limit: 5000, duration: 2592000000 },
    { name: "exports", limit: 100, duration: 2592000000 },
  ],
  meta: { plan: "growth" },
});

// Check specific resource usage on verify
const { data: verification } = await unkey.keys.verifyKey({
  key: userKey,
  ratelimits: [{ name: "ai-tokens", cost: tokenCount }],
});

if (
  verification.ratelimits?.find((r) => r.name === "ai-tokens")?.remaining === 0
) {
  return { error: "AI token quota exceeded" };
}