Shopify API versioning: releases, support windows, and upgrades.
Shopify's date-based API versions make change predictable, but only if every request, webhook, and dependency is inventoried before support ends. This guide turns the official versioning model into an operating routine for app teams.
How Shopify API versions work
Shopify releases a stable API version every three months, named for the release year and month: January, April, July, and October. Stable versions are supported for at least 12 months. This creates an overlap in which teams can test a newer version before an older one stops being supported.
The version in a request path controls the contract for that request. Shopify also returns the version actually served in the X-Shopify-API-Version response header, which should be logged and checked during upgrades.
What “fall forward” means
If an app calls a version that is no longer supported, Shopify can serve the oldest supported stable version instead. That fall-forward behavior keeps the request path reachable, but it does not make the old contract safe: removed fields, changed behavior, or new validation can still break the app.
Treat an unexpected X-Shopify-API-Version value as a migration incident, not as a compatibility guarantee.
A safe Shopify API upgrade workflow
- Inventory versioned traffic.
List Admin API calls, Storefront API calls, webhook subscriptions, libraries, Functions, and extension APIs that carry or imply a version.
- Read release notes by surface.
Map every relevant change to the app's actual fields, mutations, permissions, payloads, and merchant workflows.
- Run contract tests on the target version.
Check successful responses, errors, pagination, webhook payloads, scopes, idempotency, and client parsing.
- Observe the served version.
Log
X-Shopify-API-Versionbefore and after rollout and alert on unexpected values. - Upgrade before the final window.
Leave time for merchant-specific behavior and rollback. A version deadline should not become the deployment date.
Webhooks need their own version check
Webhook subscriptions are versioned independently of ordinary API requests. Confirm the configured webhook API version, compare payload changes, and test consumers that assume fields or enums will always be present.
Use the official versioning reference
This guide is an operating interpretation. Confirm the current release schedule and supported versions in Shopify's official API versioning documentation ↗.