> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.fluveo.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.fluveo.com/_mcp/server.

# Invoices

> **Status: `contracted_test`.** In the machine-checked test-mode contract
> (`openapi.subset.json`) and the [API Reference](/api-reference): create,
> retrieve, list, plus `finalize`. Invoice Pay is a
> separate test-only mount outside the frozen contract and API Reference.
> Served by the `fluveo-billing` sidecar (ADR 0019); promoted 2026-07-13. The
> `Stripe-Version` header is optional; send an `Idempotency-Key` on POST
> writes. See [API coverage](/api-coverage).

An Invoice is a bill to a [customer](/resources/customers) — a collection of
[invoice items](/billing/invoice-items) and/or [subscription](/billing/subscriptions)
charges that moves through `draft → open → paid` (or `void`/`uncollectible`).
[Credit notes](/billing/credit-notes) adjust an issued invoice.

Contracted test-mode operations: **create**, **retrieve**, **list**, and
**finalize**. Finalize returns the abbreviated confirmation
(`{id, object, status, total}`) — retrieve the invoice for the full
object with `customer`, `collection_method`, and `lines`. Dashboard-created invoices
use the same API through a session-scoped proxy and persist in merchant-scoped
durable Billing storage.

`POST /v1/invoices/{invoice}/pay` is mounted for TEST merchants with saved
off-session payment consent. Retry-safe money movement is enabled, but the
operation is outside the frozen contract and SDK certification. Hosted payment
completion is a separate product flow and does not promote Invoice Pay into the
API Reference.

> **Note**
>
> Paying a subscription's first invoice with `POST /v1/invoices/{invoice}/pay` does **not** enroll
> the subscription for automatic renewal: no renewal invoice and no charge follow at period end. Only
> the invoice's `hosted_invoice_url` records the customer's renewal consent. See
> [Subscriptions](/billing/subscriptions).

## Hidden from the public API

Each item below is hidden because it does not follow the Stripe parity ADR (ADR 0004 as amended). The [hidden public `/v1` registry](https://github.com/fluveohq/fluveo/blob/main/tests/api-contract/stripe/hidden-public-v1.json) lists every
hidden item. Public `/v1` answers a hidden operation as an unknown URL, refuses a hidden request
parameter or value with Stripe's `invalid_request_error`, and omits a hidden response key.

* the request parameter `mandate` of `POST /v1/invoices` (HIDE0-016)
* the response key `payment_intent` of `POST /v1/invoices` (HIDE0-017)
* the response key `payment_intent` of `POST /v1/invoices/{invoice}/finalize` (HIDE0-040)
* the response key `payment_intent` of `GET /v1/invoices` (HIDE0-049)
* the operation `GET /v1/invoices/{invoice}/hosted_invoice_url` (HIDE0-063)
* the response key `payment_intent` of `GET /v1/invoices/{invoice}` (HIDE0-064)