> ## Documentation Index
> Fetch the complete documentation index at: https://docs.newinvoice.dev/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

**2026-07-15**

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](https://docs.newinvoice.dev/concepts/errors.md).
* 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.

**2026-07-10**

Initial

**Initial dated release** — the first public API surface. `problem+json` bodies carry no
`doc_url`; list envelopes carry no `url`.

## 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.