> ## Documentation Index
> Fetch the complete documentation index at: https://invoiceapi.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Versioning & changelog

> Dated API versions, what changed in each, how to pin one, and the deprecation policy.

The API uses **dated versions** (Stripe-style). A version pins a response *shape*, so an
integration built against an older date keeps exactly that contract even as the API grows.

## Pinning a version

Send the header on any request:

```bash theme={null}
curl https://api.example.mx/v1/invoices \
  -H "Authorization: Bearer sk_live_…" \
  -H "Invoice-Version: 2026-07-15"
```

* Omit the header to track the **current** version (`2026-07-15`).
* A key may also carry a pinned version; precedence is **request header → key pin → current**.
* An unknown value is `400 request.invalid_version`.
* The resolved version is echoed on every response's `Invoice-Version` header.

Discover every version programmatically at `GET /v1/versions` (public, no auth):

```json theme={null}
{
  "object": "list",
  "current": "2026-07-15",
  "how_to_pin": "Pin a version by sending the `Invoice-Version: <date>` request header …",
  "data": [
    { "version": "2026-07-10", "summary": "Initial dated release.", "changes": ["…"] },
    { "version": "2026-07-15", "summary": "Adds machine-navigable error and list metadata.", "changes": ["…"] }
  ]
}
```

## Changelog

<Update label="2026-07-15" description="Current">
  **Adds machine-navigable error and list metadata** (both additive):

  * `problem+json` error bodies now include `doc_url` — an **absolute** deep-link to the matching
    row in the [Error reference](/concepts/errors).
  * List envelopes now include `url` — the path the list was requested from.

  A caller pinned to `2026-07-10` receives **neither** field, so an older integration's response
  shape is unchanged.
</Update>

<Update label="2026-07-10" description="Initial">
  **Initial dated release** — the first public API surface. `problem+json` bodies carry no
  `doc_url`; list envelopes carry no `url`.
</Update>

## Deprecation policy

When a version is scheduled for removal, every response served under it carries RFC 8594 headers:

| Header        | Value                                                    |
| ------------- | -------------------------------------------------------- |
| `Deprecation` | `true`                                                   |
| `Sunset`      | The HTTP-date after which the version stops being served |

Migrate to a newer version before the `Sunset` instant. Neither shipped version is deprecated
today.