Versioning and deprecation policy

API v3 is the primary public integration contract. The major version is part of every path, such as /api/v3/customisers; there is no date-based or header-selected version.

Changes within v3

Compatible additions can ship without a new major version:

new resources or operations
new optional request parameters
new response fields
new values for enums documented as expected to grow
new webhook event types

Consumers should ignore unknown response fields. For an enum marked expected to grow, preserve or report an unfamiliar value instead of treating the whole response as invalid.

A breaking change requires a new major version. Breaking changes include removing or renaming a field, parameter, path, or enum value; changing a field’s type or meaning; making an optional parameter required; tightening validation for existing input; or changing what an error code means.

Previous-generation endpoints

The reference labels documented v2 and unversioned endpoints as previous generation. They are deprecated and remain available during the migration window. New work should use v3. Their response shapes and vocabulary do not follow the v3 contract.

The generated schedule below records the active deprecation date and the Sunset scheduled six months later. Actual route removal remains gated by observed usage, affected-consumer communication, and separate approval.

Follow the v2 to v3 migration guide before the scheduled Sunset. Do not wait for route removal approval to begin the work.

Deprecation signals

Every affected operation now carries:

Deprecation: @<unix-seconds>, an RFC 9745 structured-field date
Sunset: <http-date>, an RFC 8594 HTTP date
Link: <migration-guide-url>; rel="deprecation"; type="text/html"

The changelog and migration guide will announce the same change. The operation’s behaviour does not change merely because these headers appear; it remains stable through the announced window.

Plan a migration

Discover the current v3 contract from OpenAPI JSON or OpenAPI YAML.
Create a Store-scoped key with only the scopes the replacement operations require.
Translate old fields and values with the canonical, legacy, and UI glossary.
Run old and new reads during validation when comparison helps.
Send each logical write through only one API generation. Do not race a previous-generation write against its v3 replacement.
Remove previous-generation calls and revoke any legacy wildcard key after the v3 integration is verified.

Deprecation schedule

Deprecation took effect: 22 July 2026
Sunset: 22 January 2027