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.
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.
Every removal follows the same four steps.
The deprecation is recorded in the changelog on the day it takes effect, naming the endpoint or field, the replacement, and the earliest date it may be removed.
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.
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.
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.
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.