Tiered Subscriptions

A complete pattern for SaaS subscription tiers with different API limits, rate limits, and features.

The Pattern

Store the user’s plan in key metadata
Configure limits based on plan at key creation
Optionally upgrade/downgrade by updating the key

Define Your Tiers

lib/tiers.ts

export const TIERS = {
  free: {
    name: "Free",
    credits: 100,
    refill: { interval: "daily" as const, amount: 100 },
    rateLimit: { limit: 10, duration: 60000 }, // 10/min
    features: ["api_access"],
  },
  pro: {
    name: "Pro",
    credits: 10000,
    refill: { interval: "monthly" as const, amount: 10000 },
    rateLimit: { limit: 100, duration: 60000 }, // 100/min
    features: ["api_access", "webhooks", "priority_support"],
  },
  enterprise: {
    name: "Enterprise",
    credits: null, // Unlimited
    refill: null,
    rateLimit: { limit: 1000, duration: 60000 }, // 1000/min
    features: [
      "api_access",
      "webhooks",
      "priority_support",
      "sla",
      "custom_domain",
    ],
  },
} as const;

export type Tier = keyof typeof TIERS;

Create Keys for Each Tier

lib/keys.ts

import { Unkey } from "@unkey/api";
import { TIERS, Tier } from "./tiers";

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

export async function createKeyForUser(userId: string, tier: Tier) {
  const config = TIERS[tier];

  const { data } = await unkey.keys.createKey({
    apiId: process.env.UNKEY_API_ID!,
    prefix: `sk_${tier}`,
    externalId: userId,
    name: `${config.name} API Key`,

    // Set credits based on tier (skip for unlimited)
    ...(config.credits && {
      credits: {
        remaining: config.credits,
        refill: config.refill ?? undefined,
      },
    }),

    // Set rate limits
    ratelimits: [
      {
        name: "requests",
        limit: config.rateLimit.limit,
        duration: config.rateLimit.duration,
      },
    ],

    // Store plan info in metadata
    meta: {
      tier,
      plan: config.name,
      features: config.features,
    },
  });

  return data;
}

Check Features During Verification

middleware/auth.ts

import { Unkey } from "@unkey/api";

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

export async function verifyAndCheckFeature(
  apiKey: string,
  requiredFeature?: string,
) {
  const { data } = await unkey.keys.verifyKey({ key: apiKey });

  if (!data.valid) {
    return { valid: false, code: data.code };
  }

  // Check feature access
  if (requiredFeature) {
    const features = (data.meta?.features as string[]) ?? [];
    if (!features.includes(requiredFeature)) {
      return {
        valid: false,
        code: "FEATURE_NOT_AVAILABLE",
        tier: data.meta?.tier,
      };
    }
  }

  return { valid: true, data };
}

Upgrade/Downgrade Keys

lib/keys.ts

export async function changeUserTier(keyId: string, newTier: Tier) {
  const config = TIERS[newTier];

  await unkey.keys.updateKey({
    keyId,

    // Update credits
    ...(config.credits
      ? {
          credits: {
            remaining: config.credits,
            refill: config.refill ?? undefined,
          },
        }
      : {
          // Remove credits for unlimited tier
          // (remaining: null also clears the refill schedule)
          credits: {
            remaining: null,
          },
        }),

    // Update rate limits
    ratelimits: [
      {
        name: "requests",
        limit: config.rateLimit.limit,
        duration: config.rateLimit.duration,
      },
    ],

    // Update metadata
    meta: {
      tier: newTier,
      plan: config.name,
      features: config.features,
    },
  });
}

Express Example

app.ts

import express from "express";
import { Unkey } from "@unkey/api";
import { TIERS } from "./lib/tiers";

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

// Middleware that checks tier and feature access
function requireFeature(feature: string) {
  return async (req, res, next) => {
    const apiKey = req.headers.authorization?.slice(7);

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

    let data;
    try {
      ({ data } = await unkey.keys.verifyKey({ key: apiKey }));
    } catch {
      return res.status(503).json({ error: "Service unavailable" });
    }

    if (!data.valid) {
      return res.status(401).json({ error: data.code });
    }

    const features = (data.meta?.features as string[]) ?? [];

    if (!features.includes(feature)) {
      return res.status(403).json({
        error: "Feature not available on your plan",
        required: feature,
        currentTier: data.meta?.tier,
        upgrade: "https://yourapp.com/upgrade",
      });
    }

    req.user = {
      id: data.identity?.externalId,
      tier: data.meta?.tier as string,
      features,
    };

    next();
  };
}

// Basic API access (all tiers)
app.get("/api/data", requireFeature("api_access"), (req, res) => {
  res.json({ data: [] });
});

// Webhooks (Pro and Enterprise only)
app.post("/api/webhooks", requireFeature("webhooks"), (req, res) => {
  res.json({ webhook: "created" });
});

// SLA endpoint (Enterprise only)
app.get("/api/sla-status", requireFeature("sla"), (req, res) => {
  res.json({ sla: "99.99%" });
});

app.listen(3000);

Next.js Example

app/api/webhooks/route.ts

import { Unkey } from "@unkey/api";
import { NextRequest, NextResponse } from "next/server";

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

export async function POST(req: NextRequest) {
  const apiKey = req.headers.get("authorization")?.slice(7);

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

  const { data } = await unkey.keys.verifyKey({ key: apiKey });

  if (!data.valid) {
    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
  }

  const features = (data.meta?.features as string[]) ?? [];

  if (!features.includes("webhooks")) {
    return NextResponse.json(
      {
        error: "Webhooks require a Pro or Enterprise plan",
        currentTier: data.meta?.tier,
        upgradeUrl: "/settings/billing",
      },
      { status: 403 },
    );
  }

  // Process webhook creation...
  return NextResponse.json({ created: true });
}

Handling Plan Changes

When a user upgrades via Stripe/billing:

webhooks/stripe.ts

import Stripe from "stripe";
import { changeUserTier } from "@/lib/keys";

export async function handleSubscriptionChange(event: Stripe.Event) {
  const subscription = event.data.object as Stripe.Subscription;

  // Map Stripe price IDs to tiers
  const priceToTier: Record<string, Tier> = {
    price_free: "free",
    price_pro: "pro",
    price_enterprise: "enterprise",
  };

  const newTier = priceToTier[subscription.items.data[0].price.id];
  const userId = subscription.metadata.userId;

  // Get user's key ID from your database
  const keyId = await db.users.getKeyId(userId);

  // Update the key
  await changeUserTier(keyId, newTier);

  // Optionally notify the user
  await sendEmail(userId, `You've been upgraded to ${newTier}!`);
}

Dashboard Display

Show users their current usage:

app/api/usage/route.ts

import { Unkey } from "@unkey/api";

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

export async function GET(req: NextRequest) {
  const apiKey = req.headers.get("authorization")?.slice(7)!;

  const { data } = await unkey.keys.verifyKey({ key: apiKey });

  if (!data.valid) {
    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
  }

  const tier = TIERS[data.meta?.tier as Tier];

  return NextResponse.json({
    tier: data.meta?.tier,
    plan: tier.name,
    usage: {
      credits: {
        used: tier.credits ? tier.credits - (data.credits ?? 0) : null,
        limit: tier.credits,
        remaining: data.credits,
        unlimited: tier.credits === null,
      },
      rateLimit: {
        limit: tier.rateLimit.limit,
        window: `${tier.rateLimit.duration / 1000}s`,
      },
    },
    features: tier.features,
  });
}

Response:

{
  "tier": "pro",
  "plan": "Pro",
  "usage": {
    "credits": {
      "used": 1234,
      "limit": 10000,
      "remaining": 8766,
      "unlimited": false
    },
    "rateLimit": {
      "limit": 100,
      "window": "60s"
    }
  },
  "features": ["api_access", "webhooks", "priority_support"]
}

Getting Started

Platform

Build & Deploy

Networking

Observability

CLI

Security

Keyspaces

AI Code Gen

Audit Logs

CLI

Errors

Tiered Subscriptions

The Pattern

Define Your Tiers

Create Keys for Each Tier

Check Features During Verification

Upgrade/Downgrade Keys

Express Example

Next.js Example

Handling Plan Changes

Dashboard Display

​The Pattern

​Define Your Tiers

​Create Keys for Each Tier

​Check Features During Verification

​Upgrade/Downgrade Keys

​Express Example

​Next.js Example

​Handling Plan Changes

​Dashboard Display

The Pattern

Define Your Tiers

Create Keys for Each Tier

Check Features During Verification

Upgrade/Downgrade Keys

Express Example

Next.js Example

Handling Plan Changes

Dashboard Display