About Shopify API versioning
Shopify releases new API versions on a predictable quarterly schedule, giving you time to adopt changes before older versions are retired.
Subscribe to the developer changelog and keep your contact information up to date in the Partner Dashboard to stay informed about upcoming changes.
Anchor to Versioned and unversioned APIsVersioned and unversioned APIs
Not all Shopify APIs follow the same versioning model. Versioned APIs and libraries follow the quarterly release schedule described below. Unversioned APIs and surfaces may change at any time.
| Versioning | Category | APIs | Notes |
|---|---|---|---|
| Versioned | GraphQL | Webhook payloads are versioned the same way as API responses. Shopify falls forward when your selected version becomes unsupported, and webhooks include the X-Shopify-Api-Version header to confirm which version was used. Learn more. | |
| Libraries | Versioned by major release. | ||
| Polaris | Only the last four stable versions have published docs on Shopify.dev. Older versions continue to work, but won't have dedicated reference docs. Shopify CLI prevents deploys targeting versions older than 12 months. | ||
| Unversioned |
| These APIs aren't versioned and might change at any time. | |
Anchor to Release scheduleRelease schedule
Shopify releases a new API version every three months at the beginning of the quarter, at 5pm UTC. Version names are date-based (for example, 2026-04). Each stable version is supported for a minimum of 12 months, with at least nine months of overlap between consecutive versions.
We recommend updating to the latest stable version each quarter and always specifying a version in your requests. If your app targets an unsupported version, Shopify falls forward and responds using the oldest supported stable version. For example, requests to a retired 2026-10 are served as 2027-01.
| Stable version | Release date | Supported until |
|---|---|---|
| 2026-04 | April 1, 2026 | April 1, 2027 |
| 2026-07 | July 1, 2026 | July 1, 2027 |
| 2026-10 | October 1, 2026 | October 1, 2027 |
| 2027-01 | January 1, 2027 | January 1, 2028 |
Anchor to Making requests to an API versionMaking requests to an API version
You specify the API version in your request URL. The format varies by API, so refer to each API's reference for the exact URL pattern. If you're using an official Shopify library or a Storefront SDK, version configuration is handled for you automatically.
API responses include the X-Shopify-API-Version header reflecting the version used to fulfill the request. If it differs from what you requested, your app is targeting an unsupported version and Shopify has fallen forward to the default.
Shopify supports three version types:
-
Stable: Recommended for production. Guaranteed not to change for its supported lifetime.
-
Release candidate: Published on the same date as the stable release. For example, when
2026-04releases on April 1, 2026, the2026-07release candidate also becomes available. May include backwards-incompatible changes, so not recommended for production. -
Unstable: Updated continuously with in-progress changes. Features can be added or removed at any time with no guarantee of release. Use it for early testing only.
Anchor to Deprecation practicesDeprecation practices
When part of a Shopify API becomes unnecessary, unsafe, or outdated, it's deprecated across all supported stable versions and announced in the developer changelog with migration guidance. Deprecated fields or types are removed in a subsequent release—for example, something deprecated in 2026-10 might be removed in 2027-01. Because versions overlap by at least nine months, you'll always have time to update before removal.
Deprecations are communicated through one or more of the following:
- The API health report lists resources that require changes.
- Deprecation warnings appear in API client tools like the GraphiQL Explorer.
- A notice is posted in the developer changelog.
- The API reference is updated with deprecated fields and alternatives.
- For imminent backwards-incompatible changes, your app's emergency developer contact might be notified.
If your app continues to use unsupported resources after the upgrade deadline, it's delisted from the Shopify App Store. Users are blocked from installing it for a minimum of seven days, and they'll see warnings in the Shopify admin until seven days after the last detected use of unsupported resources.
If your API is used in a standalone app (such as a desktop or mobile app), your users will need to update before the upgrade deadline. Ship your update early enough to give them time. Calls to unsupported resources could result in your app being delisted or users being blocked from installing it.
If your API is used in a standalone app (such as a desktop or mobile app), your users will need to update before the upgrade deadline. Ship your update early enough to give them time. Calls to unsupported resources could result in your app being delisted or users being blocked from installing it.