> ## Documentation Index
> Fetch the complete documentation index at: https://docs.metronome.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Rated events for finalized invoices

> [!NOTE]
>
> **PRIVATE BETA**
>
> This feature is currently in Private Beta, contact [sales@metronome.com](mailto:sales@metronome.com) for early access.
>
> Don't have a Metronome account? [Sign up to get started.](https://signup.metronome.com)

Rated events turn raw usage into priced, atomic revenue units by applying each customer's pricing, products, and credits to every event. They show exactly how much each event costs, powering precise billing, revenue and margin analysis, and customer-facing spend transparency from a single, unified dataset.

## How rated events work

When Metronome rates a usage event, it resolves the event against a customer's active contract, including their products, pricing, and any commits or credits. The result is one or more rated events, each representing a distinct priced unit of revenue.

A single usage event can produce multiple rated events in the following situations:

* **Multiple products matched:** The event matches more than one billable metric (for example, a request that counts toward both an API calls product and a data transfer product).
* **Commit boundary crossed:** Part of the usage is covered by a prepaid commit and the remainder is overage, so the covered portion and the overage portion appear as separate rated events.
* **Multiple credits applied:** Different credit types (for example, a promotional credit and a standard commit) each apply to different portions of the usage.
* **Multiple contracts matched:** The event matches more than one active contract. Note that this pattern is not a best practice, as it becomes difficult to track consumption correctly across multiple contracts.

Each rated event maps the transaction back to the customer, contract, invoice, product, and any commit or credit applied.

## What you can do with rated events

* Aggregate spend by any dimension included in event properties (region, model, cluster, workspace, user, etc.)
* Aggregate spend by any time dimension (minute, hour, day, week, month)
* Combine property dimensions with time dimensions for custom breakdowns
* Join back to the source `events` table via `transaction_id` for full end-to-end traceability

## Rated events vs. other data models

Metronome exports several related data models that serve different purposes. Understanding how they differ helps you choose the right dataset for your analysis.

| Data model | Granularity | Use it for |
| - | - | - |
| [`invoice`](https://docs.metronome.com/guides/reporting-insights/data-export/database-reference#invoice) + [`line_item`](https://docs.metronome.com/guides/reporting-insights/data-export/database-reference#line-item) | Per invoice, per product | Final invoice totals and per-product spend for a closed billing period. `invoice` holds the header (customer, period, status, total) and `line_item` contains one row per product with the final charged amount. |
| [`breakdowns_invoices`](https://docs.metronome.com/guides/reporting-insights/data-export/database-reference#breakdowns-invoices) + [`breakdowns_line_items`](https://docs.metronome.com/guides/reporting-insights/data-export/database-reference#breakdowns-line-items) | Daily (midnight-to-midnight UTC) | Daily subtotals scoped to an invoice period. `breakdowns_invoices` provides a day-level invoice summary and `breakdowns_line_items` provides the corresponding per-product daily spend. |
| [`rated_events`](#schema) | Per usage event | Event-level pricing detail. Rated events can reproduce the finalized invoice and breakdowns usage totals, but also let you slice and dice spend across any time dimension or event property dimension that is not available in aggregated models. |

Use finalized invoice data when you need final billed amounts and invoice status. Use finalized breakdowns when you need daily totals within a billing period. Use finalized rated events when you need event-level detail, custom time windows, or spend breakdowns by properties such as region, model, cluster, or user.

## Use cases

**Finance**

* **Revenue recognition:** Support complex performance obligation calculations, nth-of-month billing, and more.
* **SOX audit:** Provide auditors with complete end-to-end auditability from usage event through to paid invoice.

**Engineering**

* **Margin optimization:** Aggregate spend by compute cluster, region, resource type, or any infrastructure dimension.

**GTM**

* **Customer spend tracking:** Provide your customers with a breakdown of their spend by user, product, time period, or any other dimension.

**Product**

* **Customer-of-customer tracking:** Enable your customers to track spend by any dimension to support their own customers.

## Finalized rated events

Finalized rated events are delivered once, after the associated invoice is finalized. They represent a stable, immutable record of event rating for that billing period. The exported rated events roll up to the finalized invoice totals for usage-based products.

> [!NOTE]
>
> **DRAFT RATED EVENTS COMING SOON**
>
> Finalized rated events only cover closed billing periods. We plan to add support for draft rated events, which will be delivered daily and cover all usage sent month-to-date. This will unlock near-real-time spend analytics and the ability to answer customer billing questions during an active period. Contact us via the [Metronome support portal](https://app.metronome.com/support) if this is important to your use case.

### Schema

| Column | Type | Description |
| - | - | - |
| `rated_event_id` | `string` | The unique ID for the rating of an event (a single event can have multiple `rated_event_id`s if re-rated) |
| `transaction_id` | `string` | The unique ID of the event |
| `event_customer_id` | `string` | The `customer_id` passed in the originating event |
| `met_customer_id` | `string` | The Metronome customer ID associated with the event (useful when using ingest aliases) |
| `timestamp` | `timestamp` | The timestamp (UTC) of the event |
| `event_type` | `string` | The event type |
| `properties` | `json` | The properties of the event |
| `environment_type` | `string` | The Metronome environment, `SANDBOX` or `PRODUCTION` |
| `updated_at` | `timestamp` | The timestamp (UTC) this row was last updated |
| `snapshot_timestamp` | `timestamp` | The timestamp (UTC) of the pipeline run that produced this row |
| `billable_metric_id` | `string` | The ID of the billable metric the event is associated to |
| `quantity` | `decimal` | The quantity associated with the event |
| `rate` | `decimal` | The rate associated with the event |
| `total` | `decimal` | The total associated with the event |
| `product_id` | `string` | The ID of the associated product |
| `contract_id` | `string` | The ID of the contract associated with the rated event |
| `invoice_id` | `string` | The ID of the invoice the event is associated to |
| `credit_type_id` | `string` | The denomination of the commit (e.g. CPUs or fiat) |
| `applied_commit_or_credit_id` | `string` | The ID of the commit or credit the event is associated to |
| `commit_segment_id` | `string` | The segment of the commit associated with the event |

### Joining with other tables

| Join to | On | For |
| - | - | - |
| [`events`](https://docs.metronome.com/guides/reporting-insights/data-export/database-reference#events) | `transaction_id` | Full event payload including raw properties |
| [`customer`](https://docs.metronome.com/guides/reporting-insights/data-export/database-reference#customer) | `met_customer_id` | Customer name, aliases, custom fields. Use `met_customer_id` rather than `event_customer_id` since the latter may be an ingest alias rather than the Metronome customer ID. |
| [`invoice`](https://docs.metronome.com/guides/reporting-insights/data-export/database-reference#invoice) | `invoice_id` | Invoice totals, status, billing provider details |
| [`contracts_commits`](https://docs.metronome.com/guides/reporting-insights/data-export/database-reference#contracts-commits) | `applied_commit_or_credit_id` | Commit details, access schedule, ledger |

### Caveats

* **No support for SQL billable metrics:** Rated events are not generated for billable metrics defined using SQL. If your contract uses SQL-based billable metrics, those events will not appear in the rated events export.
* **Billable metrics added mid-billing period:** If a billable metric is created after a billing period has already started, usage events that arrived before the metric was created will not be rated. Rated events will only be generated for usage received after the billable metric was created, and the finalized invoice will reflect only that partial coverage.
* **Voided invoices are not reflected in rated events:** If an invoice is voided after it has been finalized and rated events have already been generated, the rated events for that period will not be updated or removed. To determine whether a rated event belongs to a voided invoice, join the `rated_events` table to the [`invoice`](https://docs.metronome.com/guides/reporting-insights/data-export/database-reference#invoice) table on `invoice_id` and filter on invoice status.
* **Commit and credit amounts may differ from finalized invoice totals:** When aggregating commit or credit application amounts from rated events, the totals may not match the corresponding finalized invoice. This is because rated events use improved commit application logic that has not yet been backported to finalized invoices. This discrepancy affects only commit and credit allocation — not total billed amounts — and will be resolved when the improved logic is applied to finalized invoices in a future update.

## Unrated events

Metronome processes all events delivered in the last 30 days to identify errored events, and delivers them via data export. This rolling 30-day lookback window ensures that:

* Events received **after** invoice finalization are captured in error reporting.
* **Backdated usage** (events timestamped before the current billing period) is identified and surfaced.

Use unrated events to detect data pipeline issues, investigate billing discrepancies, and verify that all usage has been correctly ingested and rated.

### Error types

| Error type | Description |
| - | - |
| Duplicate event | Generated when multiple events are sent with the same `transaction_id`. Metronome captures only the first event and ignores all subsequent duplicates. |
| Invalid Event Format | Generated when a malformed property value prevents rating (e.g. a decimal value containing a comma). |
| Missing customer | Generated when an event is sent with a `customer_id` that is not associated with any customer record in Metronome. |
| Missing contract | Generated when an event is associated with an active customer but no contract exists that covers the event. |
| Missing billable metric | Generated when an event is associated with a customer in Metronome but no billable metric is defined for the `event_type`. |
| Missing Product | Generated when a customer and billable metric match but the billable metric is not linked to any product. |
| Missing price | Generated when an event matches a customer and billable metric but no valid price is associated with the event. |
| Received after finalization | Generated when a usage event is received with a timestamp that falls within an already-finalized invoice period. \[!NOTE] Support for this error type is a planned feature and has not yet shipped as part of the private beta. |
| Unknown Error | Catch-all for any event that exits matching without a known error type. |

### Schema

| Column | Type | Description |
| - | - | - |
| `id` | `string` | Unique ID for this error record |
| `transaction_id` | `string` | Unique ID of the originating event |
| `event_customer_id` | `string` | The `customer_id` passed in the originating event |
| `met_customer_id` | `string` | The Metronome customer ID; populated when ingest aliases are used |
| `timestamp` | `timestamp` | Assigned timestamp (UTC) of the event |
| `received_at` | `timestamp` | Timestamp (UTC) the event was received by Metronome |
| `environment_type` | `string` | The Metronome environment, `SANDBOX` or `PRODUCTION` |
| `event_type` | `string` | The event type |
| `properties` | `json` | Event properties |
| `billable_metric_id` | `string` | ID of the matched billable metric |
| `product_id` | `string` | ID of the associated product |
| `contract_id` | `string` | ID of the contract associated with the event |
| `rate_card_id` | `string` | ID of the rate card associated with the event |
| `error_type` | `string` | See [error types](#error-types) above |
| `error_subtype` | `string` | Additional detail on the error type |
| `watermark_timestamp` | `timestamp` | The timestamp (UTC) of the pipeline run that produced this row |

### Caveats

* **No support for SQL billable metrics:** Unrated events are not generated for billable metrics defined using SQL. If your contract uses SQL-based billable metrics, errors for those events will not appear in the unrated events export.