# Metronome architecture primer

> Customer, contract, package, rate card, product and billable metric, with credits, commits and invoices.

Source: https://metrocli.com/docs/concepts/architecture/ · Docs index: https://metrocli.com/llms.txt

Metronome turns usage into invoices. Data flows one way: usage events become billable quantities, rate cards price them, a contract ties one customer to those prices, and each billing period ends in an invoice.

> **Metronome's reference:** [How Metronome invoices work](https://docs.metronome.com/guides/implement-metronome/core-concepts/how-invoicing-works) · [Create a contract](https://docs.metronome.com/api-reference/contracts/create-a-contract) · [Create a package](https://docs.metronome.com/api-reference/contracts/create-a-package) · [docs.metronome.com/llms.txt](https://docs.metronome.com/llms.txt). 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).

| Object | What it is | metro command |
|---|---|---|
| Customer | The account you bill. Events reach it through ingest aliases. | `metro customer create` |
| Billable metric | Filters and aggregates usage events into a quantity. | `metro usage ingest preview` |
| Product | One invoice line. Has no price of its own. | `metro product inspect` |
| Rate card | Prices for products, effective from a start date. | `metro ratecard create` |
| Package | A reusable contract template behind an alias. Never edited, only versioned. | `metro package create` |
| Contract | Connects one customer to pricing, balances and subscriptions. | `metro contract create` |
| Credits & commits | Balances that usage draws down. | `metro ledger-adjustment` |
| Subscriptions & seats | Recurring charges. Quantity is usually seats. | `metro subscription add` |
| Invoice | Built each period from usage, rates and contract terms. | `metro invoice issue-date preview` |

## How the IDs connect

| Object | Points at | Pointed at by |
|---|---|---|
| Customer | billing provider configs | usage events (`customer_id` or an ingest alias), contracts |
| Billable metric | usage events, by `event_type` and property filters | USAGE products (`billable_metric_id`) |
| Product | a billable metric (USAGE only) | rates, commits, credits, overrides |
| Rate card | products (`product_id` on each rate) | packages and direct contracts (`rate_card_id`) |
| Package | a rate card | contracts (`package_alias` or `package_id`) |
| Contract | a customer, plus a package or a rate card | invoices, transitions, hierarchy children |
| Commit or credit | a contract and a product | invoice lines (`commit_purchase`, `applied_commit_or_credit`) |
| Subscription | a SUBSCRIPTION product on the contract's rate card | seat history |
| Invoice | a customer and a contract | the billing provider's invoice (`external_invoice.id`) |

## Four facts that shape every change

1. **Packages and rate-card rates are append-only.** You never edit a package; you publish a new version behind the same alias. You never edit a rate; you add a new one from a later `starting_at`.
2. **Time is on the hour.** `starting_at`, `ending_before` and schedule timestamps must be exactly `:00:00Z`, or Metronome returns `400`.
3. **Money is in cents.** A $250 charge is `25000`. There is no "never expires" flag; the convention is an `ending_before` about 100 years out.
4. **One base URL, two tenants.** Sandbox and production both call `https://api.metronome.com`. The key decides the tenant, which is why metro makes you name it on every call.

## Which metro command touches what

| Object | Read | Write |
|---|---|---|
| Customer | `metro ops who`, `metro customer resolve` | `metro customer create` |
| Rate card | `metro catalog bind` | `metro ratecard create`, `metro ratecard add-rates` |
| Package | `metro package list`, `metro package customers` | `metro package create`, `metro package clone-version` |
| Contract | `metro ops who` | `metro contract create`, `metro contract move-plan`, `metro contract extend-trial`, `metro contract expire` |
| Credits and commits | `metro customer balances` | `metro ledger-adjustment` |
| Subscriptions and seats | `metro ops who` | `metro subscription add`, `metro subscription set-quantity`, `metro subscription seats` |
| Invoice | `metro invoice inspect --plan` | `metro invoice issue-date preview` (preview only) |

Each object has its own page in this section, with its gotchas. Metronome's docs at [docs.metronome.com](https://docs.metronome.com) are the source of truth; when this page and theirs disagree, theirs wins.