Skip to main content

​
Version in the path

Each surface carries its major version in the path: /consumer/v1 and /partner/v1. Everything in these docs describes v1. A future v2 would run side by side with v1 under its own path, with its own OpenAPI document and its own version in these docs.

​
Changes without a new version

Within v1 the API changes only additively. Expect, without notice in advance:
  • new operations, commands and webhook event types;
  • new optional request properties and query parameters;
  • new response properties and _links relations;
  • new enum values (every enum is an open set);
  • new error codes and new members in an error’s more object;
  • relaxed validation (longer maximum lengths, more accepted values).
Your client must therefore ignore unknown response properties, relations and error members, treat unknown enum values as “other”, and ignore webhook types it does not handle. Additions appear in the API reference.

​
Breaking changes and new versions

These changes never happen within v1; they only come with a new major version:
  • removing or renaming an operation, property, parameter, header or relation;
  • making an optional input required or tightening the validation of an existing field;
  • changing a property’s type, format, unit, meaning or nullability;
  • removing an enum value or rejecting a value that was accepted;
  • changing the status code or errorCode of an existing outcome;
  • changing envelopes, pagination defaults or id formats;
  • changing authentication or adding a required permission to an existing operation.
When a new major version is released, the old one stays available for at least 12 months after the new one is generally available.

​
Deprecation and sunset

A deprecated operation, or every operation of a deprecated major version, answers with these headers:
  • Deprecation (RFC 9745) is the moment the deprecation took effect, in Unix seconds.
  • Sunset (RFC 8594) is when the operation stops working.
  • Link points to the deprecation and sunset rules on this page and, where there is one, to the successor. Which operations are deprecated is shown by deprecated: true on the operation in the API reference and in the deprecation email to your technical contact.
Minimum notice between deprecation and sunset: Deprecated operations are marked on their reference page with the sunset date. After the sunset, the operation answers 410 api-version-sunset for 90 days (more.successorUrl names the successor), then 404 route-not-found. Log the Deprecation and Sunset headers in your client so you notice a deprecation even if you missed the announcement.

​
Webhook versions

Webhook bodies carry no version, and a webhook endpoint is not bound to one. The body is always {"event": {"id", "type", "timestamp"}, "payload": {…}}, and a payload only gains fields: ignore properties you do not know. A breaking change to a payload ships as a new event type, which you subscribe to when you are ready; the existing type keeps its shape.

​
Staying informed

  • Keep contacts.technicalEmail on your partner a monitored mailbox. Every deprecation and sunset is announced there, together with network address changes and sandbox resets.
  • Keep your partner’s technical contact current in the developer dashboard: deprecation notices are emailed to it when your integration still calls a deprecated operation.
  • Deprecations with a sunset within 90 days are also announced in a banner on this site.