B
Glossary
Billable Metric
A billable metric is a saved configuration that turns raw usage events into one chargeable quantity. Platforms shape the fields differently, but a definition names the events it counts, an optional filter, the property it reads, and the aggregation it applies. A billing system runs it across a period and hands the resulting number to pricing.
Key Takeaways
A billable metric is a query over ingested events that outputs one aggregate value, and pricing is calculated from that value afterward, so the metric never stores a price.
The common aggregation types are SUM, COUNT, COUNT DISTINCT, MAX, and LATEST, and every type except COUNT aggregates over a single event property.
Editing rules differ by platform: some lock a configured metric beyond its display name, while others let you change a definition or apply it to historical usage without re-ingesting data.
Event reuse differs too: some platforms let an event name feed only one metric, while others let separate metrics read different properties of the same event.
What are the types of billable metric?
Billable metrics divide by the aggregation they name, and the common types are SUM, COUNT, COUNT DISTINCT, MAX, and LATEST. Some platforms add others, such as weighted sum and custom aggregations.
Type | Aggregation | Reads | Produces |
|---|---|---|---|
Volume | SUM | A numeric property such as | Total consumed in the period |
Frequency | COUNT | Nothing beyond the event itself | Number of matching events |
Distinct entity | COUNT DISTINCT | An identifier such as | Unique entities seen |
Peak | MAX | A numeric property such as | Highest value reached |
Point in time | LATEST | A numeric property | The most recent reading in the period |
Period behavior also changes what a metric means. Some platforms separate metered metrics, which reset to zero each billing period, from recurring metrics, which persist across periods.
How do you define a billable metric?
You define a billable metric by choosing the events it counts, an optional filter, the property to read, and the aggregation, though platforms shape these fields differently. The pieces:
Event name. The identifier your application sends, which tells the platform which metric should record it. The metric ignores every usage event with a different name.
Filter. A condition on the event's properties, such as
status = success. Filters determine which events contribute to a metric.Property. The field the metric reads. COUNT metrics skip this, and the other types aggregate over a single property of the event.
Aggregation. The usage aggregation function applied to the surviving values.
The formula for a metered metric:
billable quantity = AGGREGATION(property) over events
WHERE event_name matches
AND filters match
AND timestamp falls inside the billing period
Here's one metric run over five events: event api_request, filter status = success, property tokens, aggregation SUM, unit tokens.
Timestamp | Event name | status | tokens |
|---|---|---|---|
Mar 3 |
| success | 1,200 |
Mar 7 |
| success | 800 |
Mar 9 |
| error | 5,000 |
Mar 12 |
| success | 400 |
Mar 18 |
| success | 2,500 |
The March 9 event fails the filter, the March 12 event carries the wrong name. Three survive, so the billable quantity is 1,200 + 800 + 2,500 = 4,500 tokens. At $0.60 per 1,000 tokens the invoice line reads $2.70, and the 5,000-token failure never reaches it.
What breaks billable metric definitions?
Definitions break wherever the event name, the filter, or the edit rules differ from what the product sends or the team expects.
A wrong event name. The event name you send is what routes an event to the right metric, so an event under another name isn't recorded by that metric.
A filter that doesn't match. Filters determine which events contribute to a metric, so a filter that doesn't fit what the product sends leaves those events out.
A repeated event. Some ingestion modes count multiple events sent for the same timestamp, so a repeated event adds to a SUM metric unless something removes it, and event deduplication covers that.
Changing the definition mid-period. Some platforms allow no change to a configured metric beyond its display name, some don't attribute usage sent before a metric exists to that metric by default, and others say a definition can be changed or applied to historical usage without re-ingesting data.
Related terms
A billable metric sits between the raw record and the charge. These terms sit on either side of it.
Usage event is the raw record a metric reads, including the properties its filter tests.
Usage aggregation covers the functions a metric names and how each one behaves over a period.
Usage metering ingests events and runs metric definitions against them.
Revenue leakage is what a misconfigured metric can cost.
Spending cap is the control that limits what a customer's usage can bill.
Event deduplication stops repeated events from inflating a metric's result.
FAQ
What's the difference between a billable metric and a usage event?
A usage event is one record, and a billable metric is the rule that reads many of them. The event carries an event name, a customer, properties, and usually a timestamp. The metric selects which events count, filters them, and collapses the survivors into a single number for the period.
Can one event feed more than one billable metric?
It depends on the platform. Some let separate metrics read different properties of the same event, but others let an event name feed only one metric. Check your platform's rule before designing metrics around one event.
Should you change a billable metric in the middle of a billing period?
Not without checking how your platform applies the change. Some allow no change beyond the display name, some don't attribute earlier usage to a newly defined metric by default, and others can apply a changed definition to historical usage. I'd switch pricing at a period boundary so one period isn't billed on two rules.
Back to glossary
