Skip to main content
The LLM Blueprint wraps your LLM client so that each completed call sends a usage event with its input, output, and total token counts to Dodo Payments. A meter sums those counts, so you can bill each customer for the tokens they use. The blueprint ships in the @dodopayments/ingestion-blueprints npm package as createLLMTracker().

Quick Start

Install the SDK, create a meter, and wrap your LLM client.

API Reference - Events Ingestion

The API endpoint that receives usage events.

API Reference - Meters

Create and configure meters for billing.

Usage-Based Billing Guide

Set up usage-based billing with meters from start to finish.
Use it in SaaS apps, AI chatbots, content generation tools, and any other LLM-powered application that bills by usage.

Quick Start

To track token usage, install the package, create a meter, and wrap your LLM client.
1

Install the SDK

Install the Dodo Payments Ingestion Blueprints package:
Also install the SDK for your LLM provider, such as openai, @anthropic-ai/sdk, groq-sdk, @google/genai, or ai with @ai-sdk/google.
2

Get Your API Keys

You need two API keys:
  • Dodo Payments API key: Create one under Developer → API Keys in the Dodo Payments dashboard, and store it in DODO_PAYMENTS_API_KEY. Use a test mode key while you build. A test mode key works only with test_mode.
  • LLM provider API key: The key for the provider you call, such as OpenAI, Anthropic, Groq, OpenRouter, or Google. The examples read it from variables such as OPENAI_API_KEY.
Store your API keys in environment variables. Don’t commit them to version control.
3

Create a Meter in Dodo Payments

Create a meter before you track usage:
  1. In the Dodo Payments dashboard, go to Products → Meters.
  2. Click Create Meter.
  3. Configure the meter:
    • Meter Name: A descriptive name, such as LLM Token Usage.
    • Event Name: A unique event identifier, such as llm.chat_completion.
    • Aggregation Type: Sum, to add up token counts.
    • Over Property: The token count to bill for:
      • inputTokens: input (prompt) tokens.
      • outputTokens: output (completion) tokens, including reasoning tokens when the model reports them.
      • totalTokens: input and output tokens combined.
    • Measurement Unit: The unit shown on invoices, such as tokens.
  4. Click Create Meter.
The Event Name you set here must match the eventName you pass to the SDK exactly (case-sensitive).
For detailed instructions, see the Usage-Based Billing Guide.
4

Track Token Usage

Create a tracker, wrap your LLM client, and call the client as usual:
Each completed call through the wrapped client now sends a usage event with its token counts to Dodo Payments for billing.

Configuration

Tracker Configuration

Create a tracker once at application startup and reuse it for every customer. createLLMTracker() takes these options, and it throws an error if apiKey or eventName is missing or empty:
string
required
Your Dodo Payments API key. Get it from the API Keys page.
string
The environment mode for the tracker:
  • test_mode: for development and testing. This is the default.
  • live_mode: for production.
The Dodo Payments SDKs default to live_mode instead, so set live_mode explicitly in production.
Use test_mode during development, so test traffic doesn’t create live usage events.
string
required
The event name that triggers your meter. It must match the Event Name of your Dodo Payments meter exactly (case-sensitive).
This event name links your tracked usage to the correct meter for billing calculations.
Besides wrap(), the tracker has track(response, customerId, metadata), which records usage from a response you already have, and healthCheck(), which returns true when the Dodo Payments API is reachable.

Wrapper Configuration

Pass these parameters to wrap():
object
required
Your LLM client instance, such as an OpenAI, Anthropic, Groq, or Google GenAI client, or an object that holds AI SDK functions, such as { generateText }.
string
required
The Dodo Payments customer ID of the customer to bill. It starts with cus_.
Store each user’s Dodo Payments customer ID with your user record, and pass it here. Your application’s own user ID doesn’t match a Dodo Payments customer.
object
Optional additional data to attach to each tracking event, for filtering and analysis. Each value must be a string, number, or boolean. A key named inputTokens, outputTokens, totalTokens, or model replaces the tracked value.

Complete Configuration Example

This example tracks an AI SDK call and attaches provider metadata to the event:
Automatic Tracking: The wrapper returns the provider’s response unchanged, so your code stays the same as with the original provider SDK. It sends the usage event before it returns the response, so each call waits for the ingestion request, and a failed ingestion request makes the wrapped call throw even when the provider call succeeded. Streaming responses don’t carry final token counts on the returned object, so the wrapper doesn’t track them.

Supported Providers

The tracker reads token counts from the response formats of these providers and SDKs:
Track usage with the Vercel AI SDK, which gives one interface to many LLM providers.
Tracked Metrics:
  • inputTokens → inputTokens
  • outputTokens + reasoningTokens → outputTokens
  • totalTokens → totalTokens
  • Model name: AI SDK results have no top-level model field, so the tracker records unknown. To record the model, pass it as model in the wrapper metadata, as this example does.
When you use a reasoning-capable model through the AI SDK, such as Google’s Gemini 2.5 Flash with thinking mode, the tracker adds the reported reasoning tokens to outputTokens.
Track token usage across 200+ models through OpenRouter’s unified API.
Tracked Metrics:
  • prompt_tokens → inputTokens
  • completion_tokens → outputTokens
  • total_tokens → totalTokens
  • Model name
OpenRouter gives access to models from OpenAI, Anthropic, Google, Meta, and other providers through a single API.
Track token usage from OpenAI’s GPT models.
Tracked Metrics:
  • prompt_tokens → inputTokens
  • completion_tokens → outputTokens
  • total_tokens → totalTokens
  • Model name
Track token usage from Anthropic’s Claude models.
Tracked Metrics:
  • input_tokens → inputTokens
  • output_tokens → outputTokens
  • totalTokens, calculated as input_tokens + output_tokens
  • Model name
Track token usage from models served by Groq.
Tracked Metrics:
  • prompt_tokens → inputTokens
  • completion_tokens → outputTokens
  • total_tokens → totalTokens
  • Model name
Track token usage from Google’s Gemini models through the Google GenAI SDK.
Tracked Metrics:
  • promptTokenCount → inputTokens
  • candidatesTokenCount + thoughtsTokenCount → outputTokens
  • totalTokenCount → totalTokens
  • Model version, from modelVersion
Gemini Thinking Mode: For Gemini models that think before they answer, such as Gemini 2.5 Pro, the tracker adds thoughtsTokenCount (reasoning tokens) to outputTokens, so the event reflects the full output the model produced.

Advanced Usage

Multiple Providers

To track usage across LLM providers separately, create one tracker per provider:
Use a different event name for each provider, with a meter for each, to track usage separately.

Express.js API Integration

This Express.js API tracks each chat completion for the customer who made the request. For brevity, it reads userId from the request body. userId must be the user’s Dodo Payments customer ID. In production, read it from the authenticated session instead of trusting the request body.

What Gets Tracked

Each tracked call sends one usage event to Dodo Payments with this structure:

Event Fields

string
Unique identifier for this event. The SDK generates it.Format: llm_[timestamp]_[random], where timestamp is the time in milliseconds and random is six random characters.
string
The customer ID you passed when you wrapped the client. Dodo Payments bills this customer.
string
The event name that triggers your meter. It comes from your tracker configuration.
string
ISO 8601 timestamp, set when the tracker sends the event after the provider responds.
object
Token usage and additional tracking data:
  • inputTokens: number of input (prompt) tokens used.
  • outputTokens: number of output (completion) tokens used, including reasoning tokens when applicable.
  • totalTokens: total tokens (input + output).
  • model: the LLM model used, such as gpt-4, or unknown if the response doesn’t name one.
  • provider: the LLM provider, if you included it in the wrapper metadata.
  • Any custom metadata you provided when you wrapped the client.
Reasoning Tokens: For models with reasoning capabilities, outputTokens includes both the completion tokens and the reasoning tokens.
Your Dodo Payments meter uses the metadata fields, usually inputTokens, outputTokens, or totalTokens, to calculate usage and billing.
Last modified on September 26, 2026