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

# Billing for provisioned throughput

Use provisioned-throughput billing when your customers reserve a fixed amount of capacity for a defined period and pay for usage above that commitment. This model is common for compute, data processing, and infrastructure products where a customer needs guaranteed capacity but can also consume additional capacity on demand.

In Metronome you can model the reservation as a contract-level Named Schedule, charge for it using a subscription fee, and calculate on-demand overages from usage at each reporting interval using SQL billable metrics that reference the reserved amount encoded on Named Schedules.

## In this guide

* Understand provisioned-throughput billing
* Learn how Metronome models reservations and calculates overages
* Configure SQL billable metrics, products, rates, Named Schedules, and usage events
* Show the resulting invoice and invoice breakdowns

## What is provisioned throughput?

A provisioned-throughput contract has two commercial components:

1. **Reservation fee:** A recurring fee for a fixed amount of capacity, whether or not the customer consumes all of it.
2. **On-demand overage:** A usage-based charge for capacity consumed above the reservation.

For example, a customer might reserve 120 H100 GPUs for a month and pay a fixed monthly fee. If they use 200 H100 GPUs during a 60-second interval, 120 GPUs are covered by the reservation and the remaining 80 GPUs are billed at the on-demand rate.

The reservation fee is independent of actual consumption. Customers pay for the committed capacity, then pay the on-demand rate only when their consumption exceeds that commitment.

## How Metronome models provisioned throughput

The key components to modeling this business model in Metronome are as follows:

| Component               | Role in the model                                                                                                                                |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| Usage events            | Report the customer's actual active capacity at a consistent interval. Events do not need to identify whether capacity is reserved or on demand. |
| Named Schedule          | Stores the contract's reserved capacity and the period when that value applies.                                                                  |
| SQL billable metrics    | Read raw usage and the reservation active at each event timestamp to calculate covered and on-demand quantities.                                 |
| Products and rate cards | Attach pricing to reservations and overages.                                                                                                     |
| Contract                | Holds the customer-specific reservation, negotiated rates, and other commercial terms.                                                           |

SQL billable metrics serve as the bridge between actual usage and reserved amounts encoded as contract terms. They read the reservation amount that was active at each usage interval to determine whether the customer is using under or over their reserved capacity.

For this model, you can configure two SQL billable metrics that effectively calculate:

| Metric          | Calculation                         | Used by                                                                                                                                       |
| --------------- | ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| Reserved usage  | `min(total_usage, reservation)`     | A \$0 reserved-usage product that shows how much consumption was covered by the commitment. The actual reservation fee is charged separately. |
| On-demand usage | `max(0, total_usage - reservation)` | A paid usage product that bills capacity above the commitment.                                                                                |

Follow the steps below to configure this model.

## 1. Create the SQL billable metrics

Define the SQL billable metrics first so they are available to attach when you create the products in the next step.

For each SKU and usage interval, the metrics should:

1. Aggregate raw usage at the scope where the reservation applies.
2. Look up the scheduled reservation active at the same timestamp.
3. Calculate covered usage and on-demand usage separately.

```text theme={null}
covered_usage = min(total_usage, reservation)
on_demand_usage = max(0, total_usage - reservation)
```

The example queries below reference a `reserved-instance` Named Schedule keyed by `sku`. You create that schedule on the customer's contract in [Step 3](#3-add-the-named-schedule); the metric definitions do not depend on the schedule existing yet.

### Choose the right schedule lookup

SQL billable metrics offer two functions for looking up Named Schedule values.

| Function                              | Property matching                                                                            | Return value                                                                | When to use it                                                                             |
| ------------------------------------- | -------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| `scheduleValue(name, properties, ts)` | **Exact match.** The name and properties on the schedule must exactly match the lookup.      | The value of one active schedule, or `null` when no exact match exists.     | A single authoritative value should apply at a timestamp, such as one reservation per SKU. |
| `scheduleSum(name, properties, ts)`   | **Superset match.** A schedule can include all lookup properties plus additional properties. | The sum of all active matching schedules, or `0` when there are no matches. | Multiple values should intentionally accumulate under the commercial model.                |

### Create the on-demand SQL billable metric

The following metric aggregates all H100 events into 60-second SKU totals, reads the active H100 reservation, and calculates the on-demand quantity.

```sql theme={null}
SELECT
  SUM(
    GREATEST(
      0,
      gpu_count - COALESCE(
        scheduleValue('reserved-instance', { sku: sku }, ts),
        0
      )
    )
  ) * 60 AS on_demand_gpu_seconds,
  sku
FROM (
  SELECT
    SUM(properties.gpu_count) AS gpu_count,
    properties.sku AS sku,
    DATE_TRUNC('60s', timestamp) AS ts
  FROM events
  WHERE event_type = 'gpu_usage'
  GROUP BY sku, ts
)
GROUP BY sku
```

The inner query aggregates all usage events for a SKU into a single 60-second value. For each aggregated row, the outer query looks up the reservation whose schedule properties match that row's SKU and whose segment is active at that timestamp. It subtracts the reservation from aggregated usage and floors the result at zero. When no reservation schedule matches, the example SQL treats the reservation as zero through `COALESCE(..., 0)`. In that case, all usage is billed as on demand.

The query multiplies each 60-second result by 60, so the output is in GPU-seconds. Configure the associated product's quantity conversion to divide by 3,600 before applying a GPU-hour rate.

### Create the reserved-usage SQL billable metric

To show the portion of usage covered by the reservation, use the same event aggregation and schedule lookup, but use `MIN()` instead of subtracting the reservation:

```sql theme={null}
SUM(
  MIN(
    gpu_count,
    COALESCE(scheduleValue('reserved-instance', { sku: sku }, ts), 0)
  )
) * 60 AS reserved_gpu_seconds
```

Map this metric to the reserved-usage product, which is normally priced at \$0. This gives customers visibility into the consumption covered by their commitment without charging twice for that capacity.

## 2. Create the products, rate card, and contract

Create products for the two calculated usage quantities and the fixed reservation fee, then bundle them on a rate card and attach that rate card to the customer's contract.

| Product               | Metric or charge                   | Pricing behavior                                                      |
| --------------------- | ---------------------------------- | --------------------------------------------------------------------- |
| GPU Usage — Reserved  | Reserved-usage SQL billable metric | Usage-based product priced at \$0 per GPU-hour.                       |
| GPU Usage — On-Demand | On-demand SQL billable metric      | Usage-based product priced at the contracted on-demand GPU-hour rate. |
| Reservation Fee       | Subscription charge                | Recurring fixed fee for the customer's reserved capacity.             |

Add all three products to the rate card, then create the customer's contract using that rate card. You can override the on-demand rate and reservation fee on an individual contract to reflect the customer's negotiated commercial terms.

<Info>
  **Example:** Acme's contract charges a \$100,000 monthly reservation fee for 120 H100 GPUs and \$2.00 per GPU-hour for on-demand usage. The reserved-usage product remains at \$0 per GPU-hour because the reservation fee already covers that capacity.
</Info>

## 3. Add the Named Schedule

With the contract in place, add the Named Schedule that stores the customer's reserved capacity. The SQL billable metrics created in Step 1 read from this schedule at billing time.

### What is a Named Schedule?

A Named Schedule attaches a time-varying value to a contract. Use it when a contract term, such as a customer's reserved capacity, can change over time.

Each schedule is identified within a contract by its **schedule name** and **properties**:

* The schedule name describes the kind of value, such as `reserved-instance`.
* Properties scope that value, such as `{ "sku": "gpu-H100" }`.

The same schedule name with different properties represents a different schedule. For example, a contract can have separate `reserved-instance` schedules for `gpu-H100` and `gpu-A100`.

Each schedule has one or more time-bounded segments. A segment provides the value that is active from `starting_at` until the next segment starts or `ending_before` is reached.

| Schedule name       | Properties              | Active from     | Active until      | Value    |
| ------------------- | ----------------------- | --------------- | ----------------- | -------- |
| `reserved-instance` | `{ "sku": "gpu-H100" }` | January 1, 2026 | June 15, 2026     | 120 GPUs |
| `reserved-instance` | `{ "sku": "gpu-H100" }` | June 15, 2026   | December 31, 2026 | 200 GPUs |

A Named Schedule does not affect billing by itself. The SQL billable metrics read the value active at the usage timestamp and use it in the billing calculation.

### Create a reservation using a Named Schedule

Create a reservation schedule for 120 H100 GPUs on the customer's contract:

```bash theme={null}
curl --request POST \
  --url https://api.metronome.com/v1/contracts/updateNamedSchedule \
  --header 'Authorization: Bearer $METRONOME_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '
{
  "customer_id": "$CUSTOMER_ID",
  "contract_id": "$CONTRACT_ID",
  "schedule_name": "reserved-instance",
  "properties": {
    "sku": "gpu-H100"
  },
  "starting_at": "2026-01-01T00:00:00Z",
  "ending_before": "2027-01-01T00:00:00Z",
  "value": 120
}
'
```

### Change a reservation without changing history

When the customer changes their commitment, add a new segment with the same schedule name and properties. For example, increase Acme's H100 reservation to 200 GPUs beginning June 15:

```bash theme={null}
curl --request POST \
  --url https://api.metronome.com/v1/contracts/updateNamedSchedule \
  --header 'Authorization: Bearer $METRONOME_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '
{
  "customer_id": "$CUSTOMER_ID",
  "contract_id": "$CONTRACT_ID",
  "schedule_name": "reserved-instance",
  "properties": {
    "sku": "gpu-H100"
  },
  "starting_at": "2026-06-15T00:00:00Z",
  "ending_before": "2027-01-01T00:00:00Z",
  "value": 200
}
'
```

The contract retains the 120-GPU reservation before June 15 and applies the 200-GPU reservation afterward. Historical usage events remain unchanged, and the metric uses the segment that was active at the time of each event.

## 4. Send capacity usage events

Send immutable heartbeat events at a consistent interval for each SKU and the dimensions needed to aggregate usage. This example reports active H100 GPUs for a cluster every 60 seconds:

```bash theme={null}
curl --request POST \
  --url https://api.metronome.com/v1/ingest \
  --header 'Authorization: Bearer $METRONOME_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '
[
  {
    "transaction_id": "2026-01-05T10:05:00Z_cluster_2_gpu-H100",
    "customer_id": "$CUSTOMER_ID",
    "timestamp": "2026-01-05T10:05:00Z",
    "event_type": "gpu_usage",
    "properties": {
      "cluster": "cluster_2",
      "sku": "gpu-H100",
      "gpu_count": 50
    }
  }
]
'
```

The event reports actual consumption only. It does not label the 50 GPUs as reserved or on demand. Metronome calculates that classification from the customer's contract using the SQL billable metrics and Named Schedule configured in the previous steps.

## 5. Show billing outcomes

Suppose Acme uses 200 H100 GPUs during a 60-second interval while its active reservation is 120 GPUs:

| Step                             | GPU count |
| -------------------------------- | --------- |
| Usage across all clusters        | 200       |
| Usage covered by the reservation | 120       |
| On-demand overage                | 80        |

For that interval, Metronome records:

* 7,200 covered GPU-seconds: `120 GPUs × 60 seconds`
* 4,800 on-demand GPU-seconds: `80 GPUs × 60 seconds`

The reserved-usage SQL billable metric reports the covered quantity, while the on-demand SQL billable metric reports the overage quantity. The associated products then convert GPU-seconds to GPU-hours by dividing by 3,600 before applying the applicable rate.

For an illustrative monthly invoice, the resulting line items could be:

| Line item             | Quantity         | Price             | Amount due    |
| --------------------- | ---------------- | ----------------- | ------------- |
| GPU Usage — Reserved  | 89,280 GPU-hours | \$0.00 / GPU-hour | \$0.00        |
| GPU Usage — On-Demand | 59,520 GPU-hours | \$2.00 / GPU-hour | \$119,040     |
| Reservation Fee       | 1 month          | \$100,000 / month | \$100,000     |
| **Invoice Total**     |                  |                   | **\$219,040** |

The reserved-usage line item shows the customer how much capacity was covered by their reservation. The reservation fee and on-demand line item determine the amount due.

Use invoice breakdowns to give customers hourly or daily visibility into covered and on-demand usage. This helps customers reconcile capacity consumption, reservation coverage, and overages.

## Best practices

* **Keep usage events immutable.** Store actual consumption in usage events and calculate the reservation classification from the contract rather than rewriting historical events.
* **Use the same evaluation interval as the usage events.** If events are sent every 60 seconds, apply the reservation to each 60-second interval before rolling up to the billing-period total.
* **Align schedule properties with the reservation scope.** If capacity is reserved by SKU, use `sku` as the schedule property. Include `region` or other dimensions only when the commercial reservation is scoped to those dimensions.

## Conclusion

Provisioned-throughput billing combines predictable committed revenue with flexible usage-based overages. Metronome keeps raw capacity usage immutable, stores changing commitments on the contract through Named Schedules, and uses SQL billable metrics to calculate the covered and on-demand quantities for each billing interval.

This model gives customers transparent visibility into how their reserved capacity is used while ensuring that contract changes are accurately reflected in billing.