Backward incompatible changes and migrating to a new API version

Shopify Staff
Shopify Staff
619 48 95

While the 2019-04 version of the REST and GraphQL Shopify Admin APIs does not contain any backward incompatible changes to any existing APIs, future versions inevitably will.

Once a version introduces a backwards incompatible change, developers will have nine months to migrate their apps or custom integrations to a new stable version. A version is considered stable for one year after its release. For example, if a breaking change is introduced in 2019-07, developers will have until the end of March 2020 to migrate.

This provides our community of developers with predictability and the ability to choose the migration timing for apps or custom integrations that is most convenient for them. We've curated some frequently asked questions below to help you prepare for any upcoming migrations, and any support needed during those migration efforts.

How do I know if a version contains any backwards incompatible changes?

Backwards incompatible changes will always be communicated in our developer changelog, and labelled with “action required” or “deprecation”. When making an API call that has been deprecated in the latest stable version, Shopify will return the 'X-Shopify-API-Deprecated-Reason" response header to communicate that change.  

If there is an imminent backward-incompatible change that affects your app, then the emergency developer contact for your app might be contacted about the deprecation. Read more in our docs.

How long do I have to migrate my app to a new version?

Once a version is released, it will be supported for twelve months. When a version that includes a backwards incompatible change is introduced, you will have nine months before it will become the oldest supported version. This gives you nine months to migrate once we let you know there is a breaking change included in an API version.

If your app is making deprecated calls on an API version which is soon to be unsupported, the emergency developer contact for your app might be contacted. Ensure this field is filled out in your partner dashboard for each of your apps!

How can I migrate my app when the associated admin or online store feature is not live?

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, you can test the feature by enabling a developer preview from your partner dashboard. Read more in our developer preview documentation.

How do I get support with migrating to a new version?

Every version will be released with an accompanying migration guide that highlights what API changes are included in the new version, the dates that the version is supported, and how you need to update an app to begin using the version in production. The App Platform section of our community forums will also have a new board for each API version launch. This board will be used as the main migration support channel, and a place to discuss migration efforts with other developers.

I want to migrate to the latest version, but it includes a backwards incompatible change that I’m not ready to migrate to. Can I migrate only some of my API calls?

Absolutely. Since the version is specified in the url, you can make different API calls using different versions. For example, if there was a backwards incompatible change in 2019-07 to the product API, you could migrate all other calls to this new version except for calls to the product API. When you are ready to switch over to the new version for your product calls, you would simply make the change to the URI.

What happens if I don’t migrate?

If you do not specify an API version, or call an unsupported version, Shopify will automatically append the oldest supported version to the call. It is always recommended to specify a version in your calls to avoid any unexpected behaviour, and potential downtime for your app and its users.

Can I use the release candidate in production?

No. The release candidate will eventually become the next stable version. That means API changes might still be added before the stable release without notice. You can definitely test with the release candidate, but we recommend against using it in production as the introduction of backward incompatible changes may result in downtime for your app and its users.