# Credits & commits

> Prepaid and postpaid commits, credits, access and invoice schedules, and the balance ledger.

Source: https://metrocli.com/docs/concepts/credits-and-commits/ · Docs index: https://metrocli.com/llms.txt

Credits and commits are both balances that usage draws down.

> **Metronome's reference:** [Apply credits and commits to contracts](https://docs.metronome.com/pricing-packaging/apply-credits-commits) · [List balances](https://docs.metronome.com/api-reference/credits-and-commits/list-balances) · [Get the net balance of a customer](https://docs.metronome.com/api-reference/credits-and-commits/get-the-net-balance-of-a-customer) · [Add a manual balance entry](https://docs.metronome.com/api-reference/credits-and-commits/add-a-manual-balance-entry) · [Edit a contract](https://docs.metronome.com/api-reference/contracts/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](/docs/reference/api-coverage).

- A **commit** is the customer's agreement to spend an amount over time. `PREPAID` commits are invoiced up front and drawn down by usage. `POSTPAID` commits 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 `priority` numbers draw down first.
- `rollover_fraction`, from 0 to 1, is the share carried into a renewal. `0` means the balance is lost on transition.
- Pass a `uniqueness_key` on 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](/docs/guides/credits-and-commits). Metronome docs: [Apply credits and commits](https://docs.metronome.com/pricing-packaging/apply-credits-commits).