# Invoices

> Scheduled charges, finalization and voids.

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

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](https://docs.metronome.com/guides/implement-metronome/core-concepts/how-invoicing-works) · [Void an invoice](https://docs.metronome.com/api-reference/invoices/void-an-invoice) · [Regenerate an invoice](https://docs.metronome.com/api-reference/invoices/regenerate-an-invoice) · [Update invoice issue date](https://docs.metronome.com/api-reference/contracts/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](/docs/reference/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 `DRAFT` invoices, and the new date must come before the contract's end.
- `HISTORICAL` invoices 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](/docs/guides/invoices). Metronome docs: [How invoicing works](https://docs.metronome.com/guides/implement-metronome/core-concepts/how-invoicing-works).