# Versioning and deprecation policy

Understand major versions, compatible additions, breaking changes, and the previous-generation API.

- Source URL: https://www.signcustomiser.com/help/api/guides/versioning/
- Markdown URL: https://www.signcustomiser.com/help/api/guides/versioning.md

## Guide

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](/help/api/guides/migration-v2-to-v3/) 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.

## Deprecated webhook topics

A webhook topic has no route, so the headers above cannot reach it. A deprecated topic is signalled in the catalogue instead: `GET /api/v3/webhook-event-types` returns `deprecated: true` for it, and its description opens with `Deprecated.`, then names the replacement operation and the scope that operation needs. Its page in the reference carries the same notice.

Deprecation never changes delivery. A deprecated topic keeps firing on the same events, with the same payload, signature, and retry behaviour. Nothing is removed without an announced date, and a topic may stay deprecated indefinitely with no date at all.

`form:submitted` is deprecated as of 24 August 2026. It still fires on every new submission and has no removal date. Read submissions from [`GET /api/v3/quotes`](/help/api/v3-get-list-quotes/) with the `quotes:read` scope instead, and deduplicate on the quote `id`. The webhook payload carries no stable resource id, so an integration running both cannot reliably match a delivery to a record.

## Plan a migration

1. Discover the current v3 contract from [OpenAPI JSON](/help/openapi.json) or [OpenAPI YAML](/help/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](/help/api/guides/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.

## Deprecation schedule

Deprecation took effect on 22 July 2026. Sunset is scheduled for 22 January 2027.

[Migration guide](https://www.signcustomiser.com/help/api/guides/migration-v2-to-v3/)