Shopify API versioning

API versioning allows Shopify to continuously evolve the platform while offering third-party developers a predictable path for feature upgrades and deprecations.

To ensure you always know about upcoming API changes, follow the Changelog and always keep your contact information up to date in the Partner Dashboard.

Versioned vs. unversioned APIs

Versioned APIs Unversioned APIs
  • Admin API (GraphQL and REST)
  • Storefront API
  • Webhooks
  • Developer Preview
  • OAuth endpoints (including AccessScope)
  • Liquid
  • Shopify Scripts
  • Ajax API
  • Analytics API
  • Any other resources not explicitly listed as versioned
  • 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 Admin API URLs: /admin/api/{ version }/{ endpoint }.json
    • GraphQL Admin API URL: /admin/api/{ version }/graphql.json
    • Storefront API URL: /api/{ version }/graphql.json

    For example, the following URLs call version 2020-01:

    • Rest Admin API URL: /admin/api/2020-01/products.json
    • GraphQL Admin API URL: /admin/api/2020-01/graphql.json
    • Storefront API URL: /api/2020-01/graphql.json

    There are several supported versions of the 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 Admin API call: https://{shop}.myshopify.com/admin/api/unstable/products.json
    • Example GraphQL Admin API call: https://{shop}.myshopify.com/admin/api/unstable/graphql.json
    • Example Storefront API call: https://{shop}.myshopify.com/api/unstable/graphql.json

    Deprecation practices

    Part of a Shopify API can be deprecated if it becomes unnecessary, unsafe, or outdated. It's marked as deprecated when it's removed in a newer version of the API. The deprecation is then retroactively applied to previous stable versions of the API. When a deprecation is introduced, any further details and any relevant migration information is announced in the developer changelog.

    Because each version is supported for a minimum of a year, there are always at least 9 months of overlap between versions for you to update your app to support deprecations.

    GraphQL API deprecation practices

    When Shopify deprecates a field in a GraphQL API, the change is communicated in one or more of the following ways:

    • A notice about the deprecation is posted in the the developer changelog.
    • The API reference is updated to identify the deprecated fields and applicable alternatives.
    • If there is an imminent backwards-incompatible change that affects your app, then the emergency developer contact for your app might be contacted about the deprecation.

    REST API deprecation practices

    When Shopify deprecates a resource or a property of a resource in the REST Admin API, the change is communicated in one or more of the following ways:

    • The API Health report lists which resources require changes.
    • Calls that include the deprecated behaviour return the response header X-Shopify-API-Deprecated-Reason and a link to get more information:

      ...
      X-Shopify-Shop-Api-Call-Limit → 1/40
      X-Shopify-API-Version → 2020-01
      X-Shopify-API-Deprecated-Reason → https://help.shopify.com/tutorials/update-your-app-to-a-new-api-version/2019-07#foobar-endpoint-is-removed
      ...
    • A notice about the deprecation is posted in the developer changelog.

    • The REST Admin API reference is updated to identify the affected resource and any action you need to take.

    • If there is an imminent backwards-incompatible change that affects your app, then the emergency developer contact for your app might be contacted about the deprecation.

    Webhooks

    Webhook payloads can change between API versions, similar to API response payloads. You can select the API version that you want to use for webhooks, and that version will be used for all webhooks that are sent to your app.

    When your selected API version becomes unsupported, Shopify falls forward to using the next supported stable version. Webhooks include the X-Shopify-Api-Version request header to indicate the API version that was used to generate the webhook. If this value is different than the version that you selected, then your selected API version is no longer supported.

    When your app is affected by the webhook changes in a newer API version, you should update your app before support for your selected API version is removed.

    Learn more about managing webhook versions.

    Testing with developer preview

    Shopify's developer previews give you early access to new features of Shopify so that you can build on the platform with confidence. You can test features that will be available to merchants in the upcoming months, but that haven't yet been rolled out. With developer previews, you can test your apps for compatibility, build new features, and adapt your business strategies to maximize your apps' value to merchants.

    Visit our developer changelog to see all available developer previews.

    Previewing new features

    When a new feature is accompanied by a backwards-incompatible change to our APIs, or a significant change to the online store or Shopify admin, it is included in a developer preview. You can then test the feature by creating a new development store and enabling the developer preview from your Partner Dashboard.

    Each developer preview can include several new features. When you enable a developer preview, you select the preview that includes the features that you want to have access to.

    To learn more about development stores, their features and limitations, and how to enable a developer preview, see Creating development stores.

    For backwards-incompatible changes, the timeline for developer previews is tied to the API release schedule. When a stable version introduces a backwards-incompatible change, the feature associated with the change won't be available to a merchant's Shopify admin until 9 months later, when that version of the API is the oldest supported stable version. So you have 9 months to preview a feature and prepare for it before it is released to merchants. To learn more about the API release schedule, see API versioning.

    Online store design experience developer preview

    The online store design experience developer preview allows you to:

    • Enable and disable the sections architecture on product pages.

    • Customize page sections and add content sections to product pages via the online store editor UI.

    • Edit product pages individually or use master pages, for multi-page editing.

    • Create custom sets of headers and footers with theme frame sections.

    • Integrate your apps with app sections and app snippets to surface applications on a storefront visually. This can give merchants the ability to configure settings within the context of their online store.

    Learn more about the online store design experience.

    Learn how to create a development store.