Billable metrics
Usage events, aggregations and group keys.
A usage event is a raw record of what a customer did, in a schema you design, sent to /v1/ingest. A billable metric reads that stream and turns matching events into a quantity.
Metronome's reference: Ingest events · Create a billable metric · List all billable metrics. These pages are the source of truth for every field; metro's page covers how metro handles it. What metro wraps, endpoint by endpoint: Metronome API coverage.
Usage events
| Field | Required | Notes |
|---|---|---|
customer_id | yes | The Metronome ID or an ingest alias |
event_type | yes | What happened, for example api_call |
timestamp | yes | RFC 3339, UTC |
transaction_id | yes | Up to 128 characters. Deduplicates retries. |
properties | no | Anything a metric filters, sums or groups on |
Billable metrics
A metric matches on event_type plus property filters, then aggregates: COUNT, SUM, MAX, UNIQUE or LATEST. SUM, MAX, UNIQUE and LATEST need an aggregation_key. Group keys split the quantity, for invoice breakouts or for dimensional pricing.
A USAGE product references exactly one metric through billable_metric_id.
Gotchas
- Events older than 34 days are dropped. For older periods, Metronome uses historical invoices instead.
- A request carries at most 100 events, as a JSON array even for one. A schema error in any event rejects the whole batch.
- Replaying the same
transaction_idinside 34 days does nothing, so retries are safe. Never generate a new ID on each retry. - Metrics aren't retroactive. Events ingested before a metric existed aren't counted by it.
- Renaming an
event_typethat a live metric filters on silently orphans future events. - After creation only the name can change. A different aggregation means a new metric.
- Past-dated events inside the 34-day window can still change open draft invoices and commit burn-down.
- For dimensional pricing with a code and a display name, the metric needs one compound group key holding both, for example
[["action_code", "action_display_name"]]. Separate keys fail validation.
How metro handles it
| Command | Does |
|---|---|
metro usage ingest preview --file events.json --sandbox | Offline check of an event batch, usage-ingest-preview shape |
metro catalog bind --sandbox --write | Finds your billable metric and saves its ID |
metro plan greenfield-credits-product --sandbox --json | Plans a new metric and USAGE product, preview only |
metro docs explain credits.product.decision --markdown | Decides whether you need a new metric at all |
Metronome docs: Create a billable metric.