# Billable metrics

> Usage events, aggregations and group keys.

Source: https://metrocli.com/docs/concepts/billable-metrics/ · Docs index: https://metrocli.com/llms.txt

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](https://docs.metronome.com/api-reference/usage/ingest-events) · [Create a billable metric](https://docs.metronome.com/api-reference/billable-metrics/create-a-billable-metric) · [List all billable metrics](https://docs.metronome.com/api-reference/billable-metrics/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](/docs/reference/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](/docs/concepts/products) 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_id` inside 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_type` that 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](https://docs.metronome.com/api-reference/billable-metrics/create-a-billable-metric).