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:

Reservation fee: A recurring fee for a fixed amount of capacity, whether or not the customer consumes all of it.
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:

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

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; 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.

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:

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.

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.

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:

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:

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:

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.

GET STARTED

IMPLEMENT METRONOME

EVENTS

PRICING & PACKAGING

CUSTOMERS & BILLING

INVOICING

REPORTING & INSIGHTS

PLATFORM CONFIGURATION

Billing for provisioned throughput

In this guide

What is provisioned throughput?

How Metronome models provisioned throughput

1. Create the SQL billable metrics

Choose the right schedule lookup

Create the on-demand SQL billable metric

Create the reserved-usage SQL billable metric

2. Create the products, rate card, and contract

3. Add the Named Schedule

What is a Named Schedule?

Create a reservation using a Named Schedule

Change a reservation without changing history

4. Send capacity usage events

5. Show billing outcomes

Best practices

Conclusion

​In this guide

​What is provisioned throughput?

​How Metronome models provisioned throughput

​1. Create the SQL billable metrics

​Choose the right schedule lookup

​Create the on-demand SQL billable metric

​Create the reserved-usage SQL billable metric

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

​3. Add the Named Schedule

​What is a Named Schedule?

​Create a reservation using a Named Schedule

​Change a reservation without changing history

​4. Send capacity usage events

​5. Show billing outcomes

​Best practices

​Conclusion

In this guide

What is provisioned throughput?

How Metronome models provisioned throughput

1. Create the SQL billable metrics

Choose the right schedule lookup

Create the on-demand SQL billable metric

Create the reserved-usage SQL billable metric

2. Create the products, rate card, and contract

3. Add the Named Schedule

What is a Named Schedule?

Create a reservation using a Named Schedule

Change a reservation without changing history

4. Send capacity usage events

5. Show billing outcomes

Best practices

Conclusion