Versioning and stability

We do not make breaking changes to /v1. If a change would break an integration, it ships as /v2 at a new path, and /v1 keeps running beside it.

This page says exactly what counts as breaking, so the promise can be checked.

We add to the API. Each of these can appear at any time:

• -A new endpoint.
• -A new optional field or parameter in a request.
• -A new field in a response.
• -A new value where a field takes one of a list, such as an order state.
• -A new error code, and a new webhook event type.
• -A limit that becomes more generous.

• -An endpoint is never removed or renamed.
• -A field or parameter is never removed or renamed, in a request or a response.
• -A request field that was optional never becomes required, and no new required field is added.
• -A response field that was always present is never left out, and never becomes null.
• -A field never changes type or format.
• -A value you may send is never taken away.
• -Validation never becomes stricter, and a default never changes.

Additions are only safe if your code allows for them. Three habits are enough:

• -Ignore response fields you do not recognise.
• -When a field takes one of a list of values, treat a value you do not recognise as new, not as an error. That covers states, error codes, and webhook event types.
• -Read error.code, never the wording of error.message. Codes are stable. Messages are written for people and may be reworded.

Requests work the other way. The API refuses a request field it does not know, which is why we never remove one you may be sending.

The API description at /v1/openapi.json carries a version of three numbers, such as 1.4.2. It is 1.0.0 today.

The version is in info.version, and at the top of the API reference.

We may mark a part of version 1 as deprecated. It keeps working. Deprecated means there is a newer way we recommend, not that the old one is going away.

If fixing a security problem requires changing how the API behaves, we will change it, and tell every workspace by email what changed and why.

/v1 keeps working when /v2 ships. We have no plan to retire it. If that ever changes, every workspace gets at least 12 months of notice by email.

the API reference →