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.

Anchor to Versioned APIsVersioned APIs

Anchor to Unversioned APIsUnversioned APIs

The following APIs and surfaces aren't versioned and might change at any time:

• Ajax API
• App Home App Bridge APIs (App Home Polaris components are versioned)
• Catalog API
• Customer Privacy API
• Liquid
• OAuth endpoints, including AccessScope
• Shop Minis
• Shop Pay Wallet
• Storefront Web Components
• Web Pixels API
• Any other resources not explicitly listed as versioned

Anchor to Release scheduleRelease schedule

Shopify releases a new API version every three months at 5pm UTC on the first day of the quarter. 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 inaccessible version, Shopify falls forward and responds using the oldest accessible stable version. For example, a request targeting a retired 2024-10 is served by the oldest accessible stable version instead.

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 inaccessible 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-04 releases on April 1, 2026, the 2026-07 release 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.