Meters and rate cards
Your app sends a usage event each time something billable happens: a request served, a file stored, tokens used. A meter says which events to count and how to count them. A usage price on the meter bills what it counts, with a rate card that can set a different rate for each combination of values, such as each model and token type.
Your developers send the events. Everything on this page, from the meter to the invoice, you set up in the dashboard.
Create a meter
Open the meters
In the business, open Product Catalog → Meters and select Create meter.
Name it, or use the AI tokens setup
Enter a Name. The Meter ID is made from the name, and you cannot change it later.
To bill AI usage, select Use the AI tokens setup. It fills in the event name ai_tokens, the
Sum of the tokens property, and a group by model and token_type.
Say what it counts
Under What it counts, enter the Event name that your app sends, then select the Aggregation. Most aggregations also need a Value property: the event property that holds the number, with up to 12 decimal places.
Add filters and groups
Under Filters and groups, select + Add filter to count only some events, for example only
the regions eu and us. An event counts only when each filter property has one of its values.
With no filters, every event with the event name counts.
Select + Add property under Group by to keep a separate total for each value of a property, up to 5 properties. A price on the meter can then set a rate for each combination.
Create the meter
Select Create meter. The summary at the top tells you what the meter bills, for example "We bill sum of tokens from "ai_tokens" events, for each model and token_type."
| Aggregation | The period bills |
|---|---|
| Sum | The total of the values |
| Count of events | The number of events. Events need no value |
| Minimum / Maximum | The lowest or highest value |
| Average | The total of the values divided by the number of events |
| Last value | The value of the last event |
| Unique values | The number of different values of one property, for example user_id |
| Time-weighted sum | Each event sets a level. The level × the hours or days it stayed (Time unit) |
For Sum, Last value, Maximum and Unique values, you can turn on Carry the level to the next period. Use it for seats or storage: the level stays until a new event changes it, instead of starting again each period.
More than one meter can read the same events, and a new meter also counts the events that we already keep. So you can add a meter after your app has started to send events.
Match events to customers with usage keys
An event names its customer with a usage key: an id that your app already has, such as a
workspace, user or API key id. The customer id (cus_…) always works too.
Open the customer, find the Usage keys card and select Add usage key. A key can belong to one customer only.
An event whose key no customer has is not lost. The meter page counts it under Unmatched events. When you add the key to a customer, we match those events to the customer and bill them. If their period has already been invoiced, they go on the next invoice as late usage (see below).
If you remove a usage key, new events with that key become unmatched. Events that we already matched stay with the customer.
Send a test event
On the meter page, select Send test event. Enter a usage key or customer id, and a value for each property the meter reads. The dialog fills in a value that passes each filter.
The meter page shows:
- Events in last 24 hours, with a note when some events have no subscription that bills them
- Unmatched events: events whose usage key no customer has
- Recent events, with the event time, customer, value, properties, status and key. An event in a different currency from the price says so.
Bill the meter with a usage price
Add a price to a plan or add-on
Open the plan or add-on in Product Catalog and select Add price. Set Billed to Recurring, then set Pricing model to Usage.
Select the meter
In Bill from a meter, select the meter. Without a meter, a usage price bills the usage records that you send for each subscription item instead.
Select where the amount comes from
| Amount | What we bill |
|---|---|
| Rate from the rate card | Quantity × rate, for each combination of group values |
| Amount on each event | The total of the amount property on the events, as sent |
| Cost on each event, plus a markup | The total of the cost property on the events, plus your Markup |
| Bill from the model price list | Each model at its list price or your cost, plus a markup. See Bill from the AI model price list |
| Reported cost, else the model price list | The cost of each event that has one, plus a markup. Events without a cost bill from the model price list. See Bill the reported cost first |
With Amount on each event or Cost on each event, an event whose amount or cost is in a different currency from the price is not billed. With Reported cost, else the model price list, such an event bills from the model price list.
Fill in the rate card
Set Rates are to Per unit, Per 1K units, Per 1M units or a custom number of units. AI models are usually priced per 1M tokens.
Enter the Default rate, then select + Add rate for each combination that needs a different rate. Leave a value as Any to match every value of that property.
Create the price
Select Create price, and add it to subscriptions like any other price.
Which rate applies
Each combination of values takes the row that names the most values. When two rows name the same number of values, the older row applies. A combination that no row names takes the Default rate, so a new model still bills.
With the default rate at $3.00 per 1M tokens:
| Combination | Row that bills it | Rate per 1M |
|---|---|---|
any model, input | the default rate | $3.00 |
small-v1, output | token_type is output | $15.00 |
large-v2, output | model is large-v2 and token_type is output (names more values) | $24.00 |
any model, cached_input | token_type is cached_input | $0.30 |
Rates take up to 12 decimal places. You can change the rates later, and the change applies to new subscriptions. The meter, Rates are and Amount are fixed when you create the price.
A customer can have one live subscription that bills a given meter. To bill it differently, change that subscription.
When usage closes
A meter line bills the exact period of the subscription. We close a period's usage about 6 minutes after the period ends, and the renewal invoice bills it then.
If your app holds events for some minutes before it sends them, add a wait under Settings → Billing rules → Usage close. Extra wait before usage closes takes 0 to 24 minutes, and the total wait is never more than 30 minutes. The change applies to periods that end from then on.
Late usage
An event that arrives after its period closed is not lost. It goes on the next invoice as its own line, "Usage from 1–31 Oct 2026: …", dated to its own period and priced as that period was. The line shows only the units that arrived late.
On the invoice
Each combination is one invoice line: the price name and the group values, for example "AI usage monthly · small-v1 · input". The Quantity and Unit price columns show the exact figures, decimals included, and the amount is rounded half-up to the minor unit once per line:
| Line | Quantity | Rate | Amount |
|---|---|---|---|
| AI usage monthly · small-v1 · input | 1,234,567 | $3.00 per 1M | 370.3701¢ → $3.70 |
| AI usage monthly · small-v1 · output | 456,789 | $15.00 per 1M | 685.1835¢ → $6.85 |
Total: $10.55. Under each meter line, select Price source to see the rate that billed it and where the rate came from: the rate card, a fixed rate or the default rate.
Correct an event
The dashboard shows events but does not change them. Your developers can void an event through the API until an invoice that bills its period is finalized, then send a replacement with a new key. After the invoice is finalized, issue a credit note instead. See Invoices and credit notes.
Archive a meter
On the meter page, open More and select Archive meter. You cannot archive a meter while a subscription or an active price bills from it: remove or archive that price first. After you archive it, you cannot add a price on it, and it continues to count events for periods that are open now.
Related
Usage pricing
Bill usage with tiers, volume or packages, invoice usage monthly on an annual plan, set a minimum commitment, and show customers their usage so far.
Model price list
Bill each AI model at its public list price or your own cost plus a markup, set prices per customer, check the source of every price, and see your margin.