Skip to main content
Many companies pass through the cost of LLM tokens to their customers, adding a markup to remain margin-positive. This guide describes how to bill customers for AI usage by token consumption in Metronome, including:
  • Selecting common models from Anthropic, OpenAI, Google, and other providers
  • Creating billable metrics, products, and rates based on your configured markup percentage(s)
  • Automatically syncing newly released models and provider token price changes to your rate card at your configured markup
Public previewBilling for LLM tokens is in public preview. We will continue to build on the product and there may be quick changes!

Use case

Fictional company Designr is an AI-powered design tool. Customers use Designr to generate design assets, including prototypes, mockups, and images. Designr uses common AI models and charges customers a 10% markup on underlying model costs. Designr offers several plan tiers. Its Pro Plan includes 200 Designr AI Credits — a custom pricing unit that represents usage of AI models — each month. If a customer uses all of their Designr AI Credits, they can purchase additional credits during the month. This guide shows how Designr uses billing for LLM tokens to manage its AI model rates, and Metronome Packages to model its pricing structure.

Set up with an AI coding agent

Use the Metronome billing for LLM tokens skill to guide an AI coding agent through a sandbox integration. Open your application repository, then copy and paste this prompt into your agent:
After inspecting your repository and any accessible billing state, the agent presents one concise setup checkpoint covering the inferred integration, required decisions, and credentials. Once you confirm it, the agent builds and verifies the integration. To install the skill for repeated use in a supported coding agent, run:

Set up your rate card

In Metronome, a rate card is your centralized price book, where you define pricing for all products. When you use billing for LLM tokens, Metronome automatically creates billable metrics, products, and rates for managed AI products based on the markup you enter. You do not need to create these separately. Because Designr uses a custom pricing unit, Designr AI Credits, first navigate to Offering > Pricing Units > Custom Pricing Units. Click + Add, then create a custom pricing unit named Designr AI Credits. Next, create your rate card.
Note: Billing for LLM tokens uses a USD rate card because provider prices are denominated in USD. To let customers pay in their local currency, see Let customers pay in their local currency.

Create your rate card

  1. Click Offering in the left-hand sidebar.
  2. Navigate to the Rate Cards tab and select + Add.
  3. Enter the rate card name and description, then enable Charge based on AI provider pricing (managed). You can also add a human-readable alias, such as default_rate_card, to reference the rate card more easily throughout the API.
  4. Select the AI models you want to use. You can select all models from a provider or expand the provider to select individual models.
  5. Add any other usage-based, subscription, or composite products that you want to include on the same rate card.
  6. Optionally, add group keys to split invoices or track usage by additional event properties.
  7. Click Next to proceed to the next page.

Add group keys to AI models

By default, Metronome prices AI models by model and provider. To also split invoice line items or usage data by another property from your events, such as a project or workspace ID, select Add group keys to AI models for invoicing, reporting, and analysis when you create the rate card:
  • Group invoices by sets presentation group keys, which split invoice line items by the property. Avoid properties with many possible values.
  • Track usage by sets group keys for usage tracking, which you can use for spend analysis, notifications, dashboards, and data export. These keys don’t affect pricing or invoices.
Every token usage event must include each property you add. Metronome applies the same group keys to models that it adds to the rate card later.
Set group keys when you create the rate card. Don’t add group keys to an existing managed rate card by editing its billable metrics or products directly. Metronome only syncs AI products that use the billable metrics it manages, and all AI products on a rate card must use the same group keys. If you edit them manually, Metronome can’t sync new models or provider price changes to the rate card. To change group keys, create a new managed rate card.

Set rates — Custom Pricing Unit

  1. Under Default markup for future AI models, enter the markup percentage that should automatically apply when new models are added to the rate card.
  2. In the upper-right corner of the AI models section, select USD. In the dropdown, select the Designr AI Credits custom pricing unit.
  3. In the modal, define a conversion rate between USD and Designr AI Credits. Metronome uses this rate both to price models in Designr AI Credits and to convert Designr AI Credits to USD. For example, if a model costs $4 per million input tokens and 1 Designr AI Credit = $1.50, the model’s rate is about 2.67 Designr AI Credits per million input tokens, plus your markup.
  4. Expand each model to verify its distinct rates by author, provider, and token type.
  5. Click Save.

Set rates — USD

  1. Under Default markup for future AI models, enter the markup percentage that should automatically apply when new models are added to the rate card.
  2. Enter markup percentages for each selected model, or use Apply markup to all in the upper-right corner to apply the same markup percentage to every selected model.
  3. Expand each model to verify its distinct rates by author, provider, and token type.
  4. Click Save.
Your rate card now includes the AI models you selected, priced from provider token prices plus your markup. From here, Metronome keeps these rates up to date as providers release new models and change prices. Next, you’ll define your pricing model with a Package, provision customers on it, and send token usage events to Metronome. If your customers pay in a currency other than USD, start with the next section.

Let customers pay in their local currency

Managed AI rate cards use USD, but customers can pay in their local currency, such as EUR, with Stripe Adaptive Pricing. You keep your managed USD rate card, so Metronome continues to sync newly released models and provider price changes. Invoices remain in USD, and Stripe shows customers a converted amount when they pay. To use Adaptive Pricing with Metronome invoices:
  • Set the customer’s stripe_collection_method to send_invoice. Adaptive Pricing for invoices applies when customers pay on the Stripe hosted invoice page.
  • Make sure USD is one of your Stripe settlement currencies, because Stripe requires invoices to be issued in a settlement currency. To add USD, see multi-currency settlement.
To enable Adaptive Pricing and review supported countries, restrictions, and fees, see the Stripe Adaptive Pricing docs.

Define your pricing model

Because Designr’s Pro Plan includes an allocation of 200 Designr AI Credits per month, you can create a Package to encode the credit allocation alongside the rate card you just created. In Metronome, Packages define customer-facing offerings, such as Pro Plan or Max Plan, and simplify assigning PLG customers to these offerings.

Provision customers

You are now ready to assign customers to the Pro Plan. Provisioning a customer with a package creates a contract: a customer-specific agreement that applies the terms from the package.
You can choose to collect a payment method when the user signs up, even for a free tier. This can help prevent abuse when a free tier includes a free credit allocation.
Use the API call below to provision a customer with the Pro Plan:
You can layer on or customize additional terms on this contract. For example, if a customer has exhausted all of their credits for the month and wants to purchase more, you can use Metronome’s payment-gated credit flow to charge for incremental Designr AI Credits. You can also use overrides to customize rates on a per-customer basis. Metronome only syncs the rates on the managed rate card, not contract overrides. A multiplier override applies to the current rate card price, so it follows provider price changes. An overwrite override sets a fixed price that stays the same until you change it.
Managed rate cards set the list rate for each model to the provider price plus your markup. Pricing patterns that need a different list rate, such as a $0 list rate with the real price as a commit rate to prevent overages, don’t work with managed rates. If you edit a managed list rate, Metronome treats it as a manual change and stops updating it. See How Metronome updates your rate card.

Integrate usage tracking

Ensure that your events follow the format below, with event_type set to token-billing.
Managed rate cards use fixed event and property names. Send event_type as token-billing and use the model, provider, and token property names shown here. If your existing usage events use different names, map them to this format before you send them.

Identify the model and provider

  • model is the model ID in author/model format, such as anthropic/claude-fable-5 or qwen/qwen3-coder. The author is the company that created the model.
  • provider is the inference provider that served the request, such as anthropic, openai, google, or bedrock. The same model can have different prices with different providers.
For example, a request to an Anthropic model through Amazon Bedrock uses "model": "anthropic/claude-fable-5" and "provider": "bedrock". To see every available model with its token prices and its model, author, and provider IDs, see the list of AI model prices. To find the exact model and provider values for a rate on your rate card, expand the model on the rate card. Each rate shows its author, provider, and token type. Values must match exactly for an event to match a rate. If a model or provider you need isn’t available, email token-billing-team@stripe.com to request it. The token usage fields track the number of tokens consumed by type:
  • input_tokens: Uncached input tokens
  • cached_input_tokens: Cache-read input tokens
  • output_tokens: Tokens in the response
  • cached_write_tokens: Cache-write tokens. Supported for Anthropic models and OpenAI GPT-5.6+ models only. Each model has one cache-write rate. Metronome doesn’t price cache writes differently by cache duration, such as Anthropic’s 5-minute and 1-hour cache writes. See Limitations.
Some models, including many open-weight models, have no cache-read or cache-write rates because their providers don’t offer caching or don’t report cached tokens separately. For these models, send all input tokens in input_tokens. Make sure your rate card has a rate for every token type you send for a model.

Map provider token counts

Providers report token usage in different shapes. Some include cached tokens in their total input count, while others report them separately. Before you send an event, convert the provider’s counts so that each token appears in exactly one property. For example, a cache-read token belongs in cached_input_tokens only, not in input_tokens as well. When a provider leaves out an optional count, such as cache writes for a request that didn’t write to the cache, use 0 in your calculation. In the event, you can send that property as 0 or leave it out. Either way, Metronome bills no tokens of that type. For streaming responses, send the event after the stream finishes and the provider reports final usage. Don’t estimate token counts from partial output.

OpenAI Responses

The Responses API usage object includes cache reads and cache writes in input_tokens. Subtract them to get ordinary input:
For example, given this API response:
Send these values in the usage event’s properties:

OpenAI Chat Completions

The Chat Completions API usage object includes cache reads and cache writes in prompt_tokens. Subtract them to get ordinary input:
For streaming requests, set stream_options.include_usage to true so that the final chunk includes usage. For example, given this API response:
Send these values in the usage event’s properties:

Anthropic Messages

The Messages API usage object reports ordinary input, cache reads, and cache writes as separate counts. Map them directly:
For example, given this API response:
Send these values in the usage event’s properties:

Google Gemini generateContent

For text requests without tool use, the UsageMetadata object includes cache reads in promptTokenCount. Subtract them to get ordinary input. Thinking tokens count toward output pricing, so add them to output. Gemini doesn’t report cache writes, so leave out cached_write_tokens:
For example, given this API response:
Send these values in the usage event’s properties:
The model and provider fields match each token count to the correct rate. Send events in the correct format to Metronome’s /ingest endpoint. Then navigate to the Events page to confirm that the events have matched a billable metric.

Test your end to end flow

To test your integration:
  1. Create a test customer.
  2. Provision the test customer using the rate card that you just created.
  3. Send in usage events with the test customer’s customer_id.
  4. Call the getInvoice endpoint to view the customer’s spend, and validate that each line item looks correct based on the markup you configured. You can also review the customer’s usage and invoices in the Metronome app: go to Customers, select the test customer, and open the Invoices tab.

Add additional models to your rate card

Use the Metronome billing for LLM tokens agent skill to add one or more models to an existing rate card, including models from authors or providers that aren’t on the rate card yet. Tell the agent which models to add and which rate card to use and the agent will confirm the correct markup and rates and add them to your rate card. Metronome syncs models that you add with the agent skill the same way as models you selected when you created the rate card, including automatic provider price updates. Adding a model from a new author also opts the rate card in to that author’s future models. See How Metronome updates your rate card.

Update your markup percentage

To change the markup for one model or every model on a rate card, use the Metronome billing for LLM tokens agent skill. For example:
The agent updates both the model’s markup and its rates. Customers are charged the rates on the rate card, so changing the markup alone doesn’t change what customers pay. Changing the default markup only applies to models Metronome adds later.
Don’t edit managed rates directly. If a model’s rates don’t match its markup, Metronome treats the rates as manually set and stops updating them when the provider changes its price.
Test markup changes on a sandbox rate card before you change a rate card that’s in use in production.

How Metronome updates your rate card

Metronome tracks token prices for 800+ of the most common AI models across providers, and applies new models and price changes to each managed rate card. To see the full list of models and prices that Metronome tracks, see Tokens and pricing.

New models

When an author releases a new model, Metronome adds it to every managed rate card that already has at least one of that author’s models, at the rate card’s default markup. An author is the company that created the model, the part of the model ID before the /, such as anthropic in anthropic/claude-fable-5. Metronome adds a rate for each provider that serves the new model, such as both anthropic and bedrock for a new Anthropic model. Metronome also adds rates for new providers and token types for models already on your rate card. For example, if Metronome starts tracking cache-write prices for Anthropic models on Bedrock, it adds those rates to rate cards that include those models. Metronome doesn’t add models, providers, or token types that were already in its catalog when you created the rate card but that you didn’t select. To add these, or to add models from authors that aren’t on your rate card yet, see Add additional models to your rate card.

Price changes

When a provider changes a token price, Metronome replaces the rate on your rate card with the new provider price plus the product’s markup, starting when the new price takes effect. Metronome only updates a rate if all of the following are true:
  • The rate is a flat price.
  • The current rate equals the previous provider price plus the model’s markup.
If you’ve changed a rate manually, or a rate doesn’t match its markup, Metronome assumes you’re managing that rate and doesn’t change it. To resume automatic updates, use the agent skill to recalculate the rates from current provider prices. See Update your markup percentage.

Archived rate cards

Metronome doesn’t update archived rate cards. If you unarchive a rate card, Metronome doesn’t apply the changes it skipped while the rate card was archived.

Limitations

Billing for LLM tokens is in public preview. Managed rate cards don’t support the following yet. For these cases, create and maintain the products and rates yourself, either on the same rate card or on a separate one.
  • Context-length pricing. Some providers charge higher rates for long-context requests, such as OpenAI requests over 272K input tokens. Managed rate cards use one rate per model, provider, and token type.
  • Cache-duration pricing. Anthropic charges different prices for 5-minute and 1-hour cache writes. Managed rate cards have one cache-write rate per model.
  • Service tier, speed, and regional pricing. Managed rate cards don’t support price differences for priority or high-speed tiers, or for regional versus global endpoints.
  • Tool and non-token charges. Charges such as web search fees ($10 per 1,000 searches on Anthropic and OpenAI) aren’t included. You can add a separate usage product for these.
  • Separate custom pricing unit conversions. One conversion rate both prices models in your custom pricing unit and converts that unit to USD. See Create your rate card.
  • Custom list rates. Managed list rates are always the provider price plus your markup. See Provision customers.
  • Changing group keys. You can only set group keys when you create a rate card. See Add group keys to AI models.
  • Automatic payment in local currency. Adaptive Pricing requires the send_invoice collection method. See Let customers pay in their local currency.