We're constantly trying to improve your support experience, and your feedback is extremely valuable to us.

Please take a moment to tell us about your experience today.
Sign up for future Help Center user research studies.

Migrating to a new API version

This migration guide explains how to update your app to a new API version. For each stable API version, we also provide release notes to help you know what changes you might need to make to your app to use that version. The release notes list all the changes that are introduced by an API version.

We strongly recommend that you update your apps to call the a stable API version. Updating your apps to use the latest stable version lets you spend less time configuring your apps to be version aware, and helps you to be first to market by adopting new API changes when they are released.

Update your base URL

Update the endpoint URLs that your app calls to explicitly declare the API version. Each URL should include. /api/<version name>:

  • REST endpoint example: https://<shop>.myshopify.com/admin/api/2019-04/orders.json
  • GraphQL endpoint example: https://<shop>.myshopify.com/admin/api/2019-04/graphql.json

To learn more, see Calling an API version.

Select a webhook version

You should select the API version that Shopify uses for webhooks. You can select an API version for webhooks that are created by public apps, by private apps, and from the notification settings of the Shopify admin.

To learn more, see Versioned webhooks.

Log for API response headers

You can log the following response headers to be warned when your selected API version becomes unsupported or your app is using API behaviour that is deprecated.

X-Shopify-Api-Version

The X-Shopify-Api-Version header returns the API version that was used to execute each API request. When you keep your app up to date, 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 Shopify defaulted to using the next oldest stable version.

X-Shopify-Api-Deprecated-Reason

The X-Shopify-Api-Deprecated-Reason header warns you that a response includes a resource or property that is deprecated and removed in a later API version. Log for this header to check when a function of your app is affected by an API release and needs to be updated.

Stay informed of API changes

To stay up to date with the changes in each API version, subscribe to the developer changelog, and make sure that the technical contact details are up to date for your public and private apps.

Getting support with API versioning

You can get support with API versioning by using the API Versioning community forum.

Sign up for a Partner account to get started.

Sign up