Rate cards
Rates, effective dates, rate types and dimensional rate cards.
A rate card is a catalog of prices. Each rate is one entry for a (product, starting_at) pair. Rates are time-sliced and append-only: adding a rate schedules a change from its start date, and never edits a rate in place. One rate card can serve many packages and contracts.
Metronome's reference: Create a rate card · Add rates · Get rates · Get a rate schedule. 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.
How it connects
- Each rate references
product_idand acredit_type_id(fiat, or a custom credit type). - Packages and direct contracts reference
rate_card_id. - A contract can override its rate card's prices without touching the card.
Rate types
Each rate has exactly one type.
| Type | Price |
|---|---|
FLAT | An integer price per unit |
PERCENTAGE | A fraction from 0 to 1, usually on a COMPOSITE product |
TIERED | A list of tiers, bucketed by default |
SUBSCRIPTION | A price per unit per period. Needs billing_frequency. |
CUSTOM | A free-form rate, enabled per tenant |
A rate can also carry a commit_rate: a different price while a commit or credit is drawn down.
Dimensional rate cards
A USAGE product can split pricing by event properties. pricing_group_key names the properties, for example ["region"], and each rate targets one combination with pricing_group_values, for example region: us-east-1. presentation_group_key splits how lines display without splitting the price.
New action codes are new rates on one USAGE product, not new products. The billable metric needs one compound group key holding both the code and its display name.
Gotchas
- Use
addRates, at most 100 rates per call. The single-rate endpoint is heavily rate-limited. - Adding a rate with the same product and
starting_atreplaces the rate at that time. Earlier rates stay as history. starting_atmust be a UTC hour boundary. A past hour can finalize invoice lines right away.- A contract's rate card can't be swapped. A different card means a new contract.
getRatesreturns the card's prices. A customer with overrides needs the contract's rate schedule instead.- Pricing in a custom credit type collapses usage into one "Credits conversion" line on Stripe invoices.
- A new card silently takes an alias from the card that holds it.
How metro handles it
| Command | Does |
|---|---|
metro ratecard create preflight --file=ratecard.yaml --sandbox | Create a card and its rates. Refuses a name that exists, and an alias held by another card unless --allow-alias-move. |
metro ratecard add-rates preflight --rate-card-id=<id> --file=rates.yaml --sandbox | Add rates to an existing card. Refuses a rate that already exists. |
metro rate-card dimensional preview --file input.json --sandbox | Offline preview of the dimensional-rate-card shape |
metro plan add-pricing-dimension-value --sandbox --json | Plans one new dimension value |
See Plans and rate cards. Metronome docs: Add rates.