Skip to main content

Versioning and deprecation

If you build on the Storefront API, you need to know what can change under you. This page is that promise.

What is covered​

Everything in the API reference: the endpoints, their request and response fields, and their status codes. The specification behind that page is storefront.json — download it to generate a client. The app serves the identical document at /api-docs/storefront.json on its own API host, so you can also fetch it straight from the running API.

It is generated from the API, not written by hand, so it cannot quietly fall behind. A change to any published endpoint or field fails an automated test in our build, which means no change reaches you by accident.

Not covered: the loyalty customer metafields and shop metaobjects in Shopify. They belong to the app's own theme blocks and may change in any release.

Changes we may ship at any time​

These are additive and cannot break a correctly written client:

  • a new endpoint
  • a new optional field in a response
  • a new optional field in a request
  • a new value in an existing list of values (for example a new discount type)

Your side of that deal: ignore fields you do not recognise, and do not assume a list of values is closed. Do not depend on the order of fields in a JSON response.

Changes we treat as breaking​

  • removing or renaming an endpoint or a field
  • changing the type of a field
  • changing what a status code means, or returning a new one for an existing situation
  • making an optional request field required

For any of these:

  1. It is announced in the changelog before it ships.
  2. You get at least 90 days between the announcement and the change taking effect.
  3. Merchants whose storefront calls the affected endpoint are notified by email.

Versions​

The current version is 1.0.0, shown in the specification's info.version. It follows semantic versioning: additive changes raise the minor version, breaking changes raise the major version.

The URLs are not versioned. A future major version will be published on its own path and the previous one will keep working for the announced deprecation period, so you can move at your own pace.