Versioning

The Factuarea API follows a flat-versioned URL policy (/v1) combined with an optional date header for non-breaking evolution. The commitment is clear: once published, /v1 stays stable. Incompatible changes require /v2.

URL version

https://api.factuarea.com/v1/...

v1 is our first public version (May 2026). No prior versions are accessible.

When /v2 is designed:

• /v1 and /v2 coexist for at least 12 months.
• /v1 routes do not change in that window (no payloads, status codes, fields or semantics).
• Email notices to developers with active keys, banner in the docs, headers on responses (see below).

Factuarea-Version header

Factuarea-Version: 2026-06-01

Date-versioning works the Stripe way. There is a registry of supported versions (YYYY-MM-DD dates): 2026-06-01, 2026-09-01 and 2026-10-01. The default is 2026-06-01, which is not the latest. The version that applies to a request — the effective version — is resolved in this order:

1. The Factuarea-Version request header, if you send one.
2. Otherwise, the version pinned on your API key (set when the key is created; null means no pin).
3. Otherwise, the default version, 2026-06-01.

The effective version is echoed on every response in the Factuarea-Version header, so you always know which calendar version served your request.

Factuarea-Version: 2026-06-01

Pinning a version (by header or on the key) freezes the behavior of the subset of endpoints that receive non-breaking incremental improvements (new response fields, new optional parameters). Without a header or a pin, you get the default version, 2026-06-01. Each newer date is opt-in and includes the changes of the dates before it.

Opting into 2026-09-01 changes two things, and nothing else:

Invoice vocabulary in 2026-10-01

2026-10-01 separates issuing an invoice from delivering it to the customer. It changes the invoice contract, and nothing else:

The version applies to every invoice object in any response, including conversions, recurring invoice runs, GET /v1/companies/{company}/events and listed webhook deliveries. Some parts are available on every version because they are additive or input aliases: POST /v1/companies/{company}/invoices/{invoice}/issue, the is_sent filter, generation_mode on recurring invoices, and status=sent, new_status: "sent" and scheduled_action: "draft" as aliases of issued and issue. See the release notes.

Webhook payload versions

Webhook deliveries follow the api_version of each endpoint, not the request header. The supported payload versions are 2026-05-22, 2026-10-01 and 2026-10-05. The endpoints that existed before that version were pinned to 2026-05-22 and receive invoice snapshots in the previous vocabulary. An endpoint created without api_version is pinned when it is created: with no header and no pinned key, or from the app, it stays on 2026-05-22; if the request uses the REST version 2026-10-01, it takes the latest payload version (2026-10-05). To receive the new vocabulary, create it with Factuarea-Version: 2026-10-01 or with "api_version": "2026-10-01". See Webhooks.

Errors

The header is validated against the registry:

• Malformed value (not YYYY-MM-DD, e.g. 2026-05 or 15/05/2026) → 400 parameter_invalid_format with param: "Factuarea-Version".
• Well-formed but unsupported (a valid date that is not in the registry) → 400 unsupported_api_version with param: "Factuarea-Version".

Omitting the header is never an error — it falls back to the key pin or the latest version.

What is breaking?

We consider breaking (forbidden in /v1):

• Renaming / removing JSON response fields.
• Changing a field's type (string → int).
• Changing the type/code of an existing error envelope.
• Changing status codes (e.g. returning 201 where it used to be 200).
• Making a previously optional request field required.
• Changing the format of an identifier (UUID v7 stays UUID v7).
• Removing an endpoint without a documented replacement and migration window.
• Changing the document state machine semantics.

We consider non-breaking (allowed without a new version):

• Adding new fields in responses.
• Adding optional parameters in requests.
• Adding new endpoints.
• Relaxing restrictions (raising a limit, accepting more formats).
• Adding new enum values to fields that aren't critical to client-side state machines.
• Improving error messages (changes message, not type/code).
• Reclassifying the type of an existing error envelope behind a dated version: keys pinned to an earlier date keep receiving the previous type byte for byte, and code/subcode/status never move. This is how the payment-gate errors were recategorised in 2026-09-01. Doing it without a dated version is the breaking case listed above.
• Renaming a value or changing the meaning of a field behind a dated version, as 2026-10-01 does with the invoice status: earlier dates keep the previous contract and input aliases keep existing requests working.

Deprecation policy

When an endpoint or field is marked deprecated within /v1 (e.g. a legacy alias replaced by a canonical version):

• Email notice to developers with active keys affected.
• Banner on docs.factuarea.com with the changelog.
• Headers on every response of the deprecated endpoint for at least 12 months before retirement (which only happens in /v2):

Deprecation: true
Sunset: Wed, 15 May 2027 00:00:00 GMT
Link: <https://docs.factuarea.com/changelog#v1-deprecations>; rel="deprecation"
Link: <https://docs.factuarea.com/guides/migration-from-holded>; rel="alternate"

• In /v1 the endpoint keeps working until the launch of /v2. The headers warn.
• In /v2 the endpoint is retired / replaced. The window between the first warning and /v2 is ≥ 12 months.

Migration between versions

Each migration (v1 → v2) ships with:

• A dedicated guide at docs.factuarea.com/guides/migration-v1-v2.
• Field-to-field and endpoint-to-endpoint mapping.
• Operational recommendations (keep both keys, dual-write during the transition).
• Webhooks: old events keep their shape; new events live in their own version declared in the payload.

Changelog

Every /v1 change (new field, deprecation, new event, validation fix) is published in Changelog with tags:

• feature — new field / endpoint / event.
• fix — bug fix.
• deprecation — field or endpoint marked obsolete (still active in /v1).
• breaking — only appears in /v2, never inside /v1.
• security — fix with security implications. Read it first.

Subscribe to the RSS feed at https://docs.factuarea.com/changelog.rss or follow @factuarea on X for announcements.

Stability commitment

That's the guarantee. Any exception will be communicated with generous timelines.