Credits & commits
Prepaid and postpaid commits, credits, access and invoice schedules, and the balance ledger.
Credits and commits are both balances that usage draws down.
Metronome's reference: Apply credits and commits to contracts · List balances · Get the net balance of a customer · Add a manual balance entry · Edit a contract. 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.
- A commit is the customer's agreement to spend an amount over time.
PREPAIDcommits are invoiced up front and drawn down by usage.POSTPAIDcommits are settled after usage, as a true-up. - A credit is a free allowance of spend or quantity. It has no invoice.
- Recurring commits and credits issue a new balance every period.
Access schedule and invoice schedule
| Access schedule | Invoice schedule | |
|---|---|---|
| Says | When, and how much, balance is available | What the customer is billed |
| Credit type | Fiat or a custom credit type | Must be fiat |
| On | Every commit and credit | Prepaid commits only, optional |
A prepaid commit without an invoice schedule is a pure access grant. A custom credit type on the invoice schedule returns 400 "Credit type must be a fiat currency", and only a live call reveals it.
How it connects
Commits and credits live on a contract and reference a product. applicable_product_ids or applicable_product_tags limit what they pay for; leaving both out means everything. On invoices, a purchase shows as a commit_purchase line and a drawdown as a negative applied_commit_or_credit line. A parent can share commits with child contracts.
Gotchas
- Lower
prioritynumbers draw down first. rollover_fraction, from 0 to 1, is the share carried into a renewal.0means the balance is lost on transition.- Pass a
uniqueness_keyon every grant, so a retry can't grant twice. - An invoiced commit can't be archived until its invoices are voided. Rollover commits can't be edited; edit the original on the previous contract.
- A manual ledger entry needs the commit's current
segment_id. - The net balance is the spendable truth. The balance list can differ by anything rolled over to an archived successor.
How metro handles it
| Command | Does |
|---|---|
metro customer balances --ingest-alias=acme-corp --sandbox --json | Balances, plus spendableNet, which compares the net balance with the list |
metro ledger-adjustment preflight --amount=<signed-int> | A manual ledger entry on one balance segment |
metro ledger-adjustment preflight --archive-balance-id=<id> | Archives a whole grant |
metro ledger-adjustment preflight --grant=credit or --grant=commit | Adds a new credit, or a complimentary prepaid commit, through a contract edit |
metro credit preview --shape complimentary-credit-grant --file credit.json --sandbox | Offline preview of a grant |
metro credit preview --shape paid-credit-top-up --file topup.json --sandbox | Offline preview of a payment-gated top-up |
metro refuses an addition while the net balance and the balance list disagree for that credit type, and warns with MTR-CREDIT-NET-001. When they disagree, trust the net.
See Credits and commits. Metronome docs: Apply credits and commits.