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 remain available today for existing integrations, but new work should use v3. Their response shapes and vocabulary do not follow the v3 contract.

There is no published sunset date. The ratified policy sets a six-month window from v3 general availability, gated by observed usage. That window is not a countdown until a formal deprecation announcement sets dates and migration instructions.

Do not infer a removal date from the previous-generation label. Do not describe those endpoints as sunset until their responses and public migration notice publish a Sunset date.

Deprecation signals

When an operation is formally deprecated, its response carries:

• Deprecation, following RFC 9745
• Sunset, following RFC 8594, once a date is set
• Link: <migration-guide-url>; rel="deprecation"

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

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