API versioning

The contract of /v1 only grows: new endpoints, fields and values appear, and nothing your integration already uses disappears or changes meaning. Every change is listed in the changelog.

Loading the search index…

API versioning

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 type values 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.

Following the changes

  • The changelog lists every change of the contract by date; its Atom feed brings them to your feed reader or team chat.
  • The reference and the OpenAPI file always describe the current contract: regenerate your client from the file to get new fields.