# Rate cards

> Rates, effective dates, rate types and dimensional rate cards.

Source: https://metrocli.com/docs/concepts/rate-cards/ · Docs index: https://metrocli.com/llms.txt

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](https://docs.metronome.com/api-reference/rate-cards/create-a-rate-card) · [Add rates](https://docs.metronome.com/api-reference/rate-cards/add-rates) · [Get rates](https://docs.metronome.com/api-reference/rate-cards/get-rates) · [Get a rate schedule](https://docs.metronome.com/api-reference/rate-cards/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](/docs/reference/api-coverage).

## How it connects

- Each rate references `product_id` and a `credit_type_id` (fiat, or a custom credit type).
- [Packages](/docs/concepts/packages) and direct [contracts](/docs/concepts/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_at` replaces the rate at that time. Earlier rates stay as history.
- `starting_at` must 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.
- `getRates` returns 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](/docs/guides/plans-and-rate-cards). Metronome docs: [Add rates](https://docs.metronome.com/api-reference/rate-cards/add-rates).