Meters

Define what you measure, and how the period's events roll up into one number.

A meter is the definition of a thing you measure: API calls, gigabytes stored, seats in use. It has a name, a short slug, and an optional unit of measure. Most importantly, it has an aggregation: the rule for turning a period's worth of events into the single number you bill on.

A price is linked to a meter to become a metered price. Usage events are reported, and at the end of each period the meter rolls them up using its aggregation, and that number goes through the price.

From a usage event to a charge

Record events

Your app posts usage as it happens, one event at a time or in batches.

↓ the period ends

Aggregate

The meter rolls the period's events into one number: a sum, a count, a max, or the last value.

↓ feed the number to the price

Price it

The rolled-up number goes through the item's price, the same calculators any other line uses.

↓ add to the invoice

Bill in arrears

The amount lands on the invoice at the end of the period, once the usage is known.

The five aggregations

Aggregation	What it does	Good for
Sum	Adds up the quantity of every event in the period.	API calls, gigabytes transferred, storage. The most common choice.
Count	Counts how many events landed, ignoring their quantity.	Charges where the event itself is the unit, like webhooks delivered.
Max	Takes the highest value seen in the period.	Peak usage, like the most concurrent users.
Last	Takes the value of the most recent event in the period.	A gauge, like the seat count at the end of the cycle.
Sum of cost	Adds up a cost you push on each event, not a quantity.	AI and pass-through billing, where your app knows each request's exact cost.

The first four roll up a quantity. The last one, sum of cost, is different: it sums an amount your app computes per event, and it pairs with dynamic pricing for AI usage.

Worked example

You meter API calls with the sum aggregation. Over a period your customer's app reports three events: 100 calls, 250 calls, and 80 calls. At period end the meter sums them to 430, and 430 goes through the price. If the meter used count instead, the number would be 3, the number of events.

Settings

Setting	What it does
Name	A readable name for the meter.
Slug	A short handle used to reference the meter.
Aggregation	How the period's events roll up. Chosen once and fixed after that.
Unit of measure	An optional label for what is being counted, like "GB" or "calls".

Edge cases

The aggregation cannot change after the meter is created. Changing how usage rolls up mid-life would make old and new periods disagree, so it is fixed at creation. Make a new meter if you need a different rule.
Prices link to meters, not subscriptions. A subscription meters usage through the price on one of its items, so the same meter can back many subscriptions.
A meter can be archived when you stop using it, which keeps its history without offering it for new prices.