API versioning at Shopify

Shopify's GraphQL and REST Admin APIs are versioned. This document explains how API versioning works, and how you can stay up to date with changes.

The API version release schedule

Shopify releases a new API version every 3 months at the beginning of the quarter. Version names are date based to be meaningful and semantically unambiguous (for example, 2020-01). Below is an example release schedule for 2020:

Stable version Release date Date stable version is supported until
2020-01 January 1, 2020 January 1, 2021
2020-04 April 1, 2020 April 1, 2021
2020-07 July 1, 2020 July 1, 2021
2020-10 October 1, 2020 October 1, 2021

Stable versions are released at 5pm UTC.

Each stable version is supported for a minimum of 12 months. This means that there are at least 9 months of overlap between two consecutive stable versions. When a new stable version is introduced and contains changes that affect your app, you have 9 months to test and migrate your app to the new version before support for the previous version is removed.

If your app calls a stable version that is no longer supported, then Shopify falls forward and responds to your request with the same behaviour as the oldest supported stable version. For example, in April 2020, API requests that call version 2019-04 will be served version 2019-07, because that will be the oldest supported stable version.

If your request doesn't include a version, then the API also defaults to the oldest supported stable version. However, we recommend that you specify a version with every request. By making your app version aware, you anchor your code to a specific set of features that are guaranteed to behave in the same way for the supported timeframe.

Example version support schedule

Calling an API version

Shopify API versions are explicitly declared in the URL that your app calls:

  • REST URLs: /admin/api/{ version }/{ endpoint }.json
  • GraphQL URL: /admin/api/{ version }/graphql.json

For example, the following URLs call version 2019-04:

  • Rest URL: /admin/api/2019-04/products.json
  • GraphQL URL: /admin/api/2019-04/graphql.json

There are several supported versions of the REST and GraphQL APIs available, and you specify the version that you want to use by substituting the version name in the URL. There are three types of API versions: stable, release candidate, and unstable.

Shopify's API responses contain the header X-Shopify-API-Version, which returns the API version that was used to execute the request. When you keep your app updated, this matches the API version that's specified in your request. If the returned version is different, then your app is out of date and is using the default API version.

Release candidates

Release candidates let you see what changes are scheduled for release in the next stable version so that you can begin updating your app as early as possible. API release candidates are made available on the same date that we release our stable versions. For example, when version 2020-01 is released on January 1, 2020, the release candidate for version 2020-04 will also become available.

Both backwards-incompatible and backwards-compatible changes can be added to the release candidate so that they’re available to you ahead of the stable release. For this reason, we recommend that you don’t use release candidates in production.

Unstable API versions

There is always an unstable version of the APIs available. The unstable versions contain features and changes that are still in progress, and we make backwards-incompatible and backwards-compatible changes to them regularly. Generally, changes appear in the unstable version before a stable release, but there is no guarantee that changes in the unstable version will eventually be released. A feature might be added to an unstable version but then be removed later.

You can use the unstable API versions to test new changes and features early, but you should not use them in production.

  • Example REST call: https://{shop}.myshopify.com/admin/api/unstable/products.json
  • Example GraphQL call: https://{shop}.myshopify.com/admin/api/unstable/graphql.json

Unversioned APIs

Only the REST and GraphQL Admin APIs use the versioning scheme described in this article. The following APIs are not versioned:

Sign up for a Partner account to get started.

Sign up