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:

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

{
  "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.
• 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.