Non-monotonically increasing metrics

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.

Most billable metrics in Metronome track usage that only goes up over time — for example, the total count of API calls made. These are monotonically increasing metrics. However, some metrics can fluctuate up and down over a billing period — for example, the number of connected devices or storage in use. These are non-monotonically increasing metrics, and they require a few special considerations when working with Metronome contracts, commits, credits, rate changes, and usage APIs. Non-monotonically increasing metrics typically use the latest aggregation type, which captures the most recent reported value at each point in time rather than counting or summing all events together. This page covers behavioral nuances specific to non-monotonically increasing (e.g., latest) metrics. For general information about creating billable metrics, see Create billable metrics.

​

How Metronome bills non-monotonically increasing metrics

When Metronome processes a latest metric for billing purposes, it calculates the incremental change between consecutive reporting windows rather than billing on the absolute value. This is a critical distinction that affects how charges, commits, credits, and rate changes are applied. Example: You send in the following latest values over four days: Metronome computes the daily incremental change and uses that as the billable quantity. When the reported value decreases, the incremental quantity is negative, which results in a credit back to the customer for that period.

​

Commit and credit coverage

Commits and credits apply only to the incremental usage that falls within their effective date range — not the absolute reported value.

​

Example

Suppose you have a latest metric and send the following values:

• Day 1: reported value = 7
• Day 2: reported value = 9

You create a contract with a commit that covers Day 2 onward only. Even though the absolute value on Day 2 is 9, the commit only covers the incremental quantity of 2 (the change from 7 to 9). The usage from Day 1 (quantity of 7) is not covered by the commit because it falls outside the commit’s effective range. This behavior ensures that commits and credits are applied proportionally to the usage that actually occurred during their effective period. The same logic applies to credits. In the invoice below, the $100 credit labeled “Free credit” covers only the incremental quantity that falls within its effective date range (March 17th onward). Example invoice with credit coverage: In this example, the free credit covers 25 of the 80 incremental units that accrued during the Mar 17 – Apr 1 period. The remaining 55 units are billed at the standard rate.

​

Rate changes

When a rate change takes effect mid-period, Metronome applies each rate only to the incremental usage that occurred during that rate’s effective window. This interacts with non-monotonically increasing metrics in two important ways depending on whether the value increased or decreased.

​

Scenario 1: Value increases (incremental is positive)

• Day 1: reported value = 7 (rate = $3.00/unit)
• Day 2: reported value = 9 (rate changes to $4.00/unit)

The incremental quantity on Day 2 is 2. Only that quantity of 2 is billed at the new $4.00 rate. Day 1’s quantity of 7 remains at $3.00.

​

Scenario 2: Value decreases (incremental is negative)

When the reported value drops after a rate change, the negative incremental quantity is priced at the new rate, resulting in a credit at that rate.

• Mar 1 – Mar 17: reported value reaches 40 (rate = $3.00/unit)
• Mar 17 – Apr 1: reported value drops by 10 (rate changes to $4.00/unit)

Example invoice with rate change and negative quantity: In this case, the customer is billed $120.00 for the first period at $3.00/unit, then credited $40.00 for the decrease of 10 units at the new $4.00 rate, resulting in a net total of $80.00.

​

Credits combined with rate changes and usage decreases

When a credit is present alongside a rate change and a usage decrease, the interaction between these factors can produce negative invoice totals. This happens because Metronome evaluates each charge line independently and applies credits as it encounters positive charges — it does not look ahead to account for negative charges that appear later on the invoice.

​

Example

Using the same scenario as above — a rate change from $3.00 to $4.00 on Mar 17, with usage rising to 40 then dropping by 10 — now add a $100.00 free credit that covers the full billing period. Metronome processes the charges in chronological order:

1. Mar 1 – Mar 17: 40 units × $3.00 = $120.00. The $100.00 credit is applied here, covering 33.33 units. The remaining 6.67 units are billed at $3.00.
2. Mar 17 – Apr 1: −10 units × $4.00 = −$40.00. This negative charge is processed as-is — the credit has already been consumed.

Example invoice with credit, rate change, and negative quantity: The subtotal of the charges is $80.00 (the same as the scenario without a credit). However, the full $100.00 credit was consumed against the first tranche of positive charges. The result is a negative total due of −$20.00. Keep this in mind when configuring credits for products that use non-monotonically increasing metrics, especially in combination with mid-period rate changes.

​

Invoice breakdowns

When you call the invoice breakdowns endpoint, Metronome returns the incremental quantity and its associated cost for each time window — not the absolute reported value. This includes negative quantities when usage decreases.

​

Example

You send the following latest values: The invoice breakdowns endpoint returns: The quantity column reflects the incremental change, and the cost is calculated based on that incremental quantity. Negative quantities produce negative costs (credits). This breakdown gives you a granular, day-by-day view of how the metric’s value changed and how each change was priced.

​

Usage endpoints

Unlike invoice breakdowns, the usage endpoints return the absolute latest reported value per time window — not the incremental change. The value you see depends on the granularity you request.

​

Example

You send the following latest values: With a daily breakdown, the usage endpoint returns: With no breakdown (full period), the usage endpoint returns: The value returned with no breakdown is the latest reported value across the entire queried window.

​

Summary