Invoices
Scheduled charges, finalization and voids.
An invoice is a billing statement on a customer's contract. Metronome builds it from usage, rates and contract terms, finalizes it, and sends it to the billing provider, for example Stripe.
Metronome's reference: How Metronome invoices work · Void an invoice · Regenerate an invoice · Update invoice issue date. 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.
Types
| Type | Created by |
|---|---|
USAGE | Metronome, each billing period |
SCHEDULED | Scheduled charges, or a commit's invoice schedule |
AD_HOC | A one-off charge |
PARENT_INVOICE, CHILD_INVOICE | Hierarchy aggregation |
HISTORICAL | Historical invoice creation |
Status moves DRAFT, then FINALIZED, then optionally VOID.
How it connects
An invoice belongs to a customer and a contract. Lines reference product_id; applied_commit_or_credit lines reference commit_id. external_invoice.id is the billing provider's invoice. Billing provider configs live on the customer, and contracts inherit them.
When invoices finalize
There is no finalize endpoint. Invoices finalize on their own:
USAGE: about 24 hours after the period ends.- Future-dated
SCHEDULED: at the scheduled time. - Past-dated
SCHEDULED, created through a contract edit: immediately, and pushed to Stripe within seconds.
Once an invoice finalizes, Metronome pushes it to the billing provider in the background. leave_stripe_invoices_in_draft keeps the Stripe invoice in draft while Metronome's still finalizes.
Gotchas
- Voiding works only on finalized invoices, and never refunds Stripe. Billing-provider reconciliation is separate.
- Regenerate works only on void invoices and returns a new invoice ID.
- The issue date changes only on
DRAFTinvoices, and the new date must come before the contract's end. HISTORICALinvoices finalize immediately and are never pushed to Stripe.- Stripe collapses invoices with more than 250 lines into one line, rejects decimal quantities, and accepts charges between $0.50 and $999,999.99.
- Billing provider config archives are permanent. To change collection method, archive and create a new one.
How metro handles it
| Command | Does |
|---|---|
metro invoice inspect --invoice-id <id> --sandbox --plan | A read plan: invoice get and its payments |
metro invoice issue-date preview --file issue-date.json --sandbox | Offline preview of moving a draft invoice's issue date. Apply is blocked in this release. |
metro billing-provider cutover preflight --collection-method=send_invoice | Archives the current Stripe config and sets a new one |
See Invoices. Metronome docs: How invoicing works.