What never changes in /v1
- Endpoints, fields, parameters and headers are not removed or renamed.
- A field keeps its type and format, and a field that was always returned keeps being returned.
- A request that worked keeps working: no new required fields or parameters, no stricter limits on input.
- Error
typevalues and their HTTP statuses stay the same. - An endpoint does not start requiring another scope.
The one exception is a change that closes a security vulnerability or is required by law: it may come sooner, and the changelog announces it as early as possible.
What may appear without notice
These changes do not break a client written by the rules below, so they come into /v1 at any time and are listed in the changelog:
- new endpoints, new optional parameters and request fields;
- new fields in responses and in webhook events;
- new values of enumerations in responses, such as order statuses;
- new error types, each with its HTTP status — see the error catalog;
- new event types — a webhook endpoint only gets the ones it is subscribed to.
Deprecation
When an endpoint or a field gets a better replacement, it is marked deprecated in the reference, and the changelog announces the replacement. A deprecated endpoint or field keeps working for as long as /v1 does.
A new version
A change that would break clients — removing or renaming something, changing a type, a new required input — is never made in /v1. It comes as /v2, released next to /v1 together with a migration guide.
/v1 keeps working for at least 12 months after /v2 is released. The date it stops is announced in the changelog when /v2 is released, and from then on every /v1 response carries the Deprecation (RFC 9745) and Sunset (RFC 8594) headers and a link to the announcement.