Billing for LLM tokens

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!

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:

Use the Metronome billing for LLM tokens skill at https://docs.metronome.com/.well-known/agent-skills/metronome-token-billing/skill.md to monetize this app.

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:

npx --yes skills add https://docs.metronome.com --skill metronome-token-billing --yes

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 Credits — a custom pricing unit — each month. If a customer uses all of their Designr Credits, they can purchase additional credits during the month.

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 Credits, first navigate to Offering > Pricing Units > Custom Pricing Units. Click + Add, then create a custom pricing unit named Designr 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

Click Offering in the left-hand sidebar.
Navigate to the Rate Cards tab and select + Add.
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.
Select the AI models you want to use. You can select all models from a provider or expand the provider to select individual models.
Add any other usage-based, subscription, or composite products that you want to include on the same rate card.
Click Next to proceed to the next page.

Set rates — Custom Pricing Unit

Under Default markup for future AI models, enter the markup percentage that should automatically apply when new models are added to the rate card.
In the upper-right corner of the AI models section, select USD. In the dropdown, select the Designr Credits custom pricing unit.
In the modal, define a conversion rate between USD and Designr Credits.
Expand each model to verify its distinct rates by author, provider, and token type.
Click Save.

Set rates — USD

Under Default markup for future AI models, enter the markup percentage that should automatically apply when new models are added to the rate card.
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.
Expand each model to verify its distinct rates by author, provider, and token type.
Click Save.

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 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. Use the API call below to provision a customer with the Pro Plan:

curl --request POST \
  --url https://api.metronome.com/v1/contracts/create \
  --header "Authorization: Bearer $METRONOME_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "customer_id": "13117714-3f05-48e5-a6e9-a66093f13b4d",
    "package_alias": "designr_pro",
    "starting_at": "2026-08-28T00:00:00.000Z"
  }'

response = client.v1.contracts.create(
  customer_id="13117714-3f05-48e5-a6e9-a66093f13b4d",
  package_alias="designr_pro",
  starting_at="2026-08-28T00:00:00.000Z"
)

await client.v1.contracts.create({
  customer_id: '13117714-3f05-48e5-a6e9-a66093f13b4d',
  package_alias: 'designr_pro',
  starting_at: '2026-08-28T00:00:00.000Z'
});

response = client.v1.contracts.create(
  customer_id: '13117714-3f05-48e5-a6e9-a66093f13b4d',
  package_alias: 'designr_pro',
  starting_at: '2026-08-28T00:00:00.000Z'
)

contractStartingTime, err := time.Parse(time.RFC3339Nano, "2026-08-28T00:00:00.000Z")
if err != nil {
  panic(err.Error())
}

contractResponse, err := client.V1.Contracts.New(context.TODO(), metronome.ContractNewParams{
  CustomerID:   metronome.F("13117714-3f05-48e5-a6e9-a66093f13b4d"),
  PackageAlias: metronome.F("designr_pro"),
  StartingAt:   metronome.F(contractStartingTime),
})
if err != nil {
  panic(err.Error())
}

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 Credits. You can also use overrides to customize rates on a per-customer basis.

Integrate usage tracking

Ensure that your events follow the format below, with event_type set to token-billing.

curl --request POST \
  --url https://api.metronome.com/v1/ingest \
  --header "Authorization: Bearer $METRONOME_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '[{
    "transaction_id": "b1d52889-f8f7-4aee-a41f-f2eb89789ece",
    "timestamp": "2026-08-24T18:38:50.597Z",
    "customer_id": "13117714-3f05-48e5-a6e9-a66093f13b4d",
    "event_type": "token-billing",
    "properties": {
      "model": "anthropic/claude-fable-5",
      "provider": "anthropic",
      "input_tokens": 233,
      "cached_input_tokens": 1459,
      "output_tokens": 83,
      "cached_write_tokens": 210
    }
  }]'

response = client.v1.usage.ingest(
  usage=[
    {
      "transaction_id": "b1d52889-f8f7-4aee-a41f-f2eb89789ece",
      "timestamp": "2026-08-24T18:38:50.597Z",
      "customer_id": "13117714-3f05-48e5-a6e9-a66093f13b4d",
      "event_type": "token-billing",
      "properties": {
        "model": "anthropic/claude-fable-5",
        "provider": "anthropic",
        "input_tokens": 233,
        "cached_input_tokens": 1459,
        "output_tokens": 83,
        "cached_write_tokens": 210
      }
    }
  ]
)

async function main() {
  await client.v1.usage.ingest({
    usage: [{
      transaction_id: 'b1d52889-f8f7-4aee-a41f-f2eb89789ece',
      timestamp: '2026-08-24T18:38:50.597Z',
      customer_id: '13117714-3f05-48e5-a6e9-a66093f13b4d',
      event_type: 'token-billing',
      properties: {
        model: 'anthropic/claude-fable-5',
        provider: 'anthropic',
        input_tokens: 233,
        cached_input_tokens: 1459,
        output_tokens: 83,
        cached_write_tokens: 210
      }
    }],
  });
}

main();

result = metronome.v1.usage.ingest(
    usage: [
      {
        transaction_id: 'b1d52889-f8f7-4aee-a41f-f2eb89789ece',
        timestamp: '2026-08-24T18:38:50.597Z',
        customer_id: '13117714-3f05-48e5-a6e9-a66093f13b4d',
        event_type: 'token-billing',
        properties: {
          model: 'anthropic/claude-fable-5',
          provider: 'anthropic',
          input_tokens: 233,
          cached_input_tokens: 1459,
          output_tokens: 83,
          cached_write_tokens: 210
        }
      }
    ]
)

puts(result)

err := client.V1.Usage.Ingest(context.TODO(), metronome.UsageIngestParams{
  Usage: []metronome.UsageIngestParamsUsage{{
    TransactionID: metronome.F("b1d52889-f8f7-4aee-a41f-f2eb89789ece"),
    Timestamp:     metronome.F("2026-08-24T18:38:50.597Z"),
    CustomerID:    metronome.F("13117714-3f05-48e5-a6e9-a66093f13b4d"),
    EventType:     metronome.F("token-billing"),
    Properties: metronome.F(map[string]interface{}{
      "model":               "anthropic/claude-fable-5",
      "provider":            "anthropic",
      "input_tokens":        233,
      "cached_input_tokens": 1459,
      "output_tokens":       83,
      "cached_write_tokens": 210,
    }),
  }},
})
if err != nil {
  panic(err.Error())
}

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

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:

cache_reads = usage.input_tokens_details?.cached_tokens ?? 0
cache_writes = usage.input_tokens_details?.cache_write_tokens ?? 0
input_tokens = usage.input_tokens - cache_reads - cache_writes
cached_input_tokens = cache_reads
cached_write_tokens = cache_writes
output_tokens = usage.output_tokens

For example, given this API response:

{
  "usage": {
    "input_tokens": 16000,
    "input_tokens_details": {
      "cached_tokens": 12000,
      "cache_write_tokens": 3000
    },
    "output_tokens": 400
  }
}

Send these values in the usage event’s properties:

{
  "input_tokens": 1000,
  "cached_input_tokens": 12000,
  "cached_write_tokens": 3000,
  "output_tokens": 400
}

OpenAI Chat Completions

The Chat Completions API usage object includes cache reads and cache writes in prompt_tokens. Subtract them to get ordinary input:

cache_reads = usage.prompt_tokens_details?.cached_tokens ?? 0
cache_writes = usage.prompt_tokens_details?.cache_write_tokens ?? 0
input_tokens = usage.prompt_tokens - cache_reads - cache_writes
cached_input_tokens = cache_reads
cached_write_tokens = cache_writes
output_tokens = usage.completion_tokens

For streaming requests, set stream_options.include_usage to true so that the final chunk includes usage. For example, given this API response:

{
  "usage": {
    "prompt_tokens": 16000,
    "prompt_tokens_details": {
      "cached_tokens": 12000,
      "cache_write_tokens": 3000
    },
    "completion_tokens": 400
  }
}

Send these values in the usage event’s properties:

{
  "input_tokens": 1000,
  "cached_input_tokens": 12000,
  "cached_write_tokens": 3000,
  "output_tokens": 400
}

Anthropic Messages

The Messages API usage object reports ordinary input, cache reads, and cache writes as separate counts. Map them directly:

input_tokens = usage.input_tokens
cached_input_tokens = usage.cache_read_input_tokens ?? 0
cached_write_tokens = usage.cache_creation_input_tokens ?? 0
output_tokens = usage.output_tokens

For example, given this API response:

{
  "usage": {
    "input_tokens": 1000,
    "cache_read_input_tokens": 12000,
    "cache_creation_input_tokens": 3000,
    "output_tokens": 400
  }
}

Send these values in the usage event’s properties:

{
  "input_tokens": 1000,
  "cached_input_tokens": 12000,
  "cached_write_tokens": 3000,
  "output_tokens": 400
}

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:

cache_reads = usageMetadata.cachedContentTokenCount ?? 0
input_tokens = usageMetadata.promptTokenCount - cache_reads
cached_input_tokens = cache_reads
output_tokens = (usageMetadata.candidatesTokenCount ?? 0) + (usageMetadata.thoughtsTokenCount ?? 0)

For example, given this API response:

{
  "usageMetadata": {
    "promptTokenCount": 13000,
    "cachedContentTokenCount": 12000,
    "candidatesTokenCount": 300,
    "thoughtsTokenCount": 100
  }
}

Send these values in the usage event’s properties:

{
  "input_tokens": 1000,
  "cached_input_tokens": 12000,
  "output_tokens": 400
}

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:

Create a webhook destination by navigating to Developer > Notifications > Webhooks.
Create a test customer.
Provision the test customer using the rate card that you just created.
Send in usage events with the test customer’s customer_id.
Call the getInvoice endpoint to view the customer’s spend, and validate that each line item looks correct based on the markup you configured.

Add 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. 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.

Update your markup percentage

Use the Metronome billing for LLM tokens agent skill to update the markup percentage for an individual model or every model on a rate card.

Token price updates

When model providers release new models, Metronome automatically updates your rate card to include those models at the default markup specified on the rate card. When a model provider changes a token price, Metronome automatically updates the price on your rate card while preserving the markup configured on the rate card.

​Set up with an AI coding agent

​Use case

​Set up your rate card

​Create your rate card

​Set rates — Custom Pricing Unit

​Set rates — USD

​Let customers pay in their local currency

​Define your pricing model

​Provision customers

​Integrate usage tracking

​Map provider token counts

​OpenAI Responses

​OpenAI Chat Completions

​Anthropic Messages

​Google Gemini generateContent

​Test your end to end flow

​Add models to your rate card

​Update your markup percentage

​Token price updates

Set up with an AI coding agent

Use case

Set up your rate card

Create your rate card

Set rates — Custom Pricing Unit

Set rates — USD

Let customers pay in their local currency

Define your pricing model

Provision customers

Integrate usage tracking

Map provider token counts

OpenAI Responses

OpenAI Chat Completions

Anthropic Messages

Google Gemini `generateContent`

Test your end to end flow

Add models to your rate card

Update your markup percentage

Token price updates