Skip to navigation
Billing

Invoices

A bill issued to a customer.

Status: contracted_test. In the machine-checked test-mode contract (openapi.subset.json) and the 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.

An Invoice is a bill to a customer — a collection of invoice items and/or subscription charges that moves through draft → open → paid (or void/uncollectible). 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.

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.

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 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)