# Versioning and deprecation policy

This is the commitment we make to partners about how the Partner API changes
over time, and the process we follow internally to honour it. It is written to
be quotable in a diligence questionnaire.

### What we consider a breaking change

A change is breaking if a correct integration built against the documented
contract could stop working because of it. That includes:

- removing an endpoint, or changing its path or method
- removing a response field, or narrowing its type
- adding a required request field, or making an optional one required
- tightening validation so that a previously accepted request is rejected


The following are **not** breaking, and ship without notice:

- adding an endpoint
- adding an optional request field
- adding a response field
- adding a value to a request enum
- relaxing validation


Partners should parse responses permissively — ignore unknown fields rather
than rejecting them — so that additive changes stay non-breaking in practice.

### The deprecation process

Every removal follows the same four steps.

#### 1. Announce

The deprecation is recorded in the [changelog](/products/partner-api/changelog)
on the day it takes effect, naming the endpoint or field, the replacement, and
the earliest date it may be removed.

#### 2. Mark

The endpoint is marked `deprecated` in the OpenAPI schema, so it renders struck
through in the API reference and is flagged by generated clients and linters.
Its description names the replacement. A deprecated field carries the same
marker on the field itself.

#### 3. Wait

**A deprecated endpoint remains callable for a minimum of three months from the
changelog announcement.** In practice most live far longer; three months is the
floor, not the target. Nothing is removed inside that window.

We may hide a deprecated endpoint from the published reference before removing
it, once it has been deprecated for **six months or more**. Hiding is a
documentation change only — **a hidden endpoint still works**. It exists to stop
new integrations adopting a route that is on its way out, without disturbing
partners already calling it.

#### 4. Contact, then remove

Before an endpoint is removed we identify every partner we can observe calling
it and contact them directly. We do not rely on the partner having read the
changelog. If a partner is still calling a deprecated endpoint at the end of the
window, we work with them on a migration date rather than removing it underneath
them.

### Versioning

The Partner API is versioned in the URL path (`/api/v1/`, `/api/v2/`). A new
major version is introduced when a domain is redesigned rather than extended —
for example V2 Pockets replacing V1 Accounts.

**Introducing V2 of a domain does not deprecate V1 of every other domain.** The
two versions run side by side, and V1 continues to receive new endpoints in
domains where no V2 equivalent exists. A partner integrating today will use a
mix of V1 and V2 routes, and that is expected and supported.

An endpoint in V1 is deprecated only when its V2 replacement has reached
functional parity. At that point it follows the process above.