Enforcement

Tier templates

Tier templates let you define a spend limit for a pricing tier and apply it automatically to every user on that tier. Instead of configuring a budget per user, you configure it once per tier — the SDK enforces it for everyone who matches.

When to use tier templates

Tier templates are the right starting point for most teams. They're especially useful when:

  • You have a freemium or tiered pricing model and want to cap AI spend per tier
  • You're reselling AI features and need per-customer spend control without registering every user individually
  • You want a sensible default limit that applies to all users without extra configuration

Step 1 — Create a template in the dashboard

Go to Enforcement and click + New template. Configure:

TierAny string label — e.g. "free", "pro", "enterprise". Must match exactly what you pass as the tier tag in your SDK calls.
Spend limitMaximum USD spend per window for any single user on this tier.
WindowThe rolling period — day, week, or month. Monthly is the most common.
ActionWhat happens when the limit is reached. warn is recommended — calls proceed and onBudgetWarning fires. block throws LLMBudgetExceededError.
Alert thresholdFire onBudgetWarning at this percentage of the limit. Default 80%. Gives you a heads-up before the hard limit is reached.

Step 2 — Pass the tier tag on each call

Add a tier field to your trackedCall() or trackedStream() call. The value must match the tier label you configured in the dashboard exactly.

import { trackedCall } from '@llmcosttracker/sdk'await trackedCall({client, params, apiKey: 'lct_live_your_key_here', group: 'search', userId: session.userId, tier: session.plan, // 'free' | 'pro' | 'enterprise'})

The tier value is case-sensitive. "free" and "Free" are treated as different tiers. Use lowercase consistently.

Step 3 — Handle the action

If your template action is warn, pass an onBudgetWarning callback to be notified when a user approaches or hits the limit:

await trackedCall({client, params, apiKey, userId: session.userId, tier: session.plan, onBudgetWarning: (result) => {
    console.warn(
      `User ${result.budgetConfig.userId} reached `,
      `$${result.spendUsd.toFixed(4)} of $${result.limitUsd} limit`
    )},})

If your action is block, wrap the call in a try/catch and handle LLMBudgetExceededError. See Handling blocks for details.

How spend is counted

Spend is tracked per user, not per tier. Each user on the free tier gets their own counter — one heavy user hitting their limit does not affect other free tier users. The template defines the limit; the counter is per user.

Per-user overrides

If a specific user needs a different limit than their tier, create a per-user budget for that user ID. It will take precedence over the tier template automatically — no changes needed at the call site.

Next: Per-user budgets →