Metronome architecture primer
Customer, contract, package, rate card, product and billable metric, with credits, commits and invoices.
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 · Create a contract · Create a package · 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.
- 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
- Customer
- Credits & commits
Balances that usage draws down. Commits are bought, credits are granted.
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
- Credits & commits
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
- 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. - Time is on the hour.
starting_at,ending_beforeand schedule timestamps must be exactly:00:00Z, or Metronome returns400. - Money is in cents. A $250 charge is
25000. There is no "never expires" flag; the convention is anending_beforeabout 100 years out. - 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 are the source of truth; when this page and theirs disagree, theirs wins.