Versioning and deprecation

The API is versioned in the path: /api/v1. This is the promise for version 1.

Within v1 we may add new endpoints, new optional request fields, new response fields, new webhook event types and new permissions. We will not remove or rename an endpoint, field, error code, event or permission, and we will not change the meaning of one, within v1. Clients must ignore response fields and event types they do not know.

A deprecation is announced at least six months before anything stops working. From the announcement the affected responses carry Deprecation and Sunset headers, with a Link to the explanation; the change is in the changelog and emailed to the owner and managers of every store that used it in the last 30 days. Anything that does not meet this promise is a bug.

A breaking change that cannot be made additively would be a new version (/api/v2), served alongside v1 for at least six months after v2 is announced.

The headers

Watch for them in your client's logs: a request that returns Sunset is one to change before that date. The notice is never shorter than six months; a test in the API's repository fails if a sunset is set closer than that.

What the promise does not cover

• The wording of message fields (branch on code).
• The order of fields inside a JSON object, and the contents of opaque values: cursors, ids' internal format.
• The rate-limit numbers: they are published and changed with a note in the changelog.
• A bug fix, and a security change where waiting would hurt (announced the same day).

Building against it

• Ignore fields you do not know. Do not fail on an unknown status or event type; log it and carry on.
• Pin nothing but the path: there is no version header and no date to choose.
• Read the changelog.