@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 withtest_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.
3
Create a Meter in Dodo Payments
Create a meter before you track usage:For detailed instructions, see the Usage-Based Billing Guide.
- In the Dodo Payments dashboard, go to Products → Meters.
- Click Create Meter.
- 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.
- Meter Name: A descriptive name, such as
- Click Create Meter.
The Event Name you set here must match the
eventName you pass to the SDK exactly (case-sensitive).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.
live_mode instead, so set live_mode explicitly in production.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.
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 towrap():
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_.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 attachesprovider 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:AI SDK (Vercel)
AI SDK (Vercel)
Track usage with the Vercel AI SDK, which gives one interface to many LLM providers.Tracked Metrics:
inputTokens→inputTokensoutputTokens+reasoningTokens→outputTokenstotalTokens→totalTokens- Model name: AI SDK results have no top-level
modelfield, so the tracker recordsunknown. To record the model, pass it asmodelin the wrappermetadata, 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.OpenRouter
OpenRouter
Track token usage across 200+ models through OpenRouter’s unified API.Tracked Metrics:
prompt_tokens→inputTokenscompletion_tokens→outputTokenstotal_tokens→totalTokens- Model name
OpenAI
OpenAI
Track token usage from OpenAI’s GPT models.Tracked Metrics:
prompt_tokens→inputTokenscompletion_tokens→outputTokenstotal_tokens→totalTokens- Model name
Anthropic Claude
Anthropic Claude
Track token usage from Anthropic’s Claude models.Tracked Metrics:
input_tokens→inputTokensoutput_tokens→outputTokenstotalTokens, calculated asinput_tokens+output_tokens- Model name
Groq
Groq
Track token usage from models served by Groq.Tracked Metrics:
prompt_tokens→inputTokenscompletion_tokens→outputTokenstotal_tokens→totalTokens- Model name
Google Gemini
Google Gemini
Track token usage from Google’s Gemini models through the Google GenAI SDK.Tracked Metrics:
promptTokenCount→inputTokenscandidatesTokenCount+thoughtsTokenCount→outputTokenstotalTokenCount→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:Express.js API Integration
This Express.js API tracks each chat completion for the customer who made the request. For brevity, it readsuserId 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 asgpt-4, orunknownif 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.