Shopify API Version Upgrade: A Quarterly Checklist for Custom Apps
Shopify ships a new Admin API version every three months. How to find the version your custom app calls, read the release notes, test the upgrade and deploy it safely.
In this guide
A custom Shopify app can break without anyone changing a line of code. The usual cause is the API version. Every request names a version, every version has an end date, and when that date passes Shopify quietly answers with a newer one. Fields disappear, behaviour shifts, and the first sign is often a wrong number in a report.
The fix is a short routine you run every quarter. This checklist is written for the person who owns a custom app or integration, whether you write the code yourself or need to know what to ask the developer who does.
How Shopify API versions work
Shopify’s versioning docs set the rules:
- A new version every quarter. Versions are released at 5pm UTC on January 1, April 1, July 1 and October 1, and named by date, such as
2026-10. - At least 12 months of support. Each stable version is supported for a minimum of 12 months, and consecutive versions overlap by at least nine months.
- Old versions fall forward. When an app requests a version that is no longer accessible, Shopify responds using the oldest accessible stable version instead.
- Every response says which version answered. The
X-Shopify-API-Versionheader shows the version used. If it differs from the one you asked for, your app is calling an expired version.
Shopify also publishes a release candidate for the next version on the same day as each stable release, and an unstable version that changes continuously. Neither is meant for production. As of October 2026, the versioning page lists 2026-10 as the latest stable version and 2027-01 as the release candidate.
The fall-forward rule is why this matters. Your app keeps working in the sense that requests succeed, but it is now running against a version nobody tested it on.
What a version covers
Versioning applies to more than one API. The versioning page lists the GraphQL Admin, Storefront, Customer Account, Functions, Partner, Payments Apps and Webhooks APIs among the versioned ones, plus Polaris UI extensions. For a typical custom app, check at least three places:
| Where the version lives | What it controls |
|---|---|
The request URL, such as /admin/api/2026-10/graphql.json |
Admin API calls |
api_version under [webhooks] in shopify.app.toml |
How webhook payloads are serialized |
| Each extension’s configuration | Admin, checkout or Function extensions |
A common gap: the API calls get upgraded and the webhook version stays years behind, so handlers keep parsing an old payload shape.
The quarterly checklist
Run this in the weeks after each release on January 1, April 1, July 1 and October 1. Shopify’s own recommendation is to update to the latest stable version each quarter; at the very least, never let a version you use come within a quarter of its end date.
1. Find the version you actually call
Do not trust the config file alone. Check what Shopify sees:
- Search the code for
/admin/api/and for the version setting in your Shopify client library. Note every version string you find. - Read the response header. Log
X-Shopify-API-Versionon a real request and compare it with what you asked for. - Check the Dev Dashboard. For apps managed there, the app’s Logs show the API version on each request entry, and alerts flag deprecated API calls and extensions pinned to an unsupported API version.
- Ask Shopify for deprecated calls. The Deprecated API calls endpoint, available only for custom apps, lists deprecated calls from the past 30 days with the endpoint, last call time, migration deadline and the earliest version to move to.
Write down one line per app: current version, webhook version, extension versions, and the date each stops being supported.
2. Read the release notes between your version and the target
Shopify publishes release notes for every version, each at its own page such as 2026-10. Read every version between the one you run and the one you are moving to, not just the latest.
As you read, keep only what touches your app:
- objects, fields or mutations your code uses that were changed, deprecated or removed;
- webhook topics or payload fields your handlers read;
- changes to resources the app depends on, such as orders, inventory or products.
Shopify’s versioning docs explain that deprecations are announced across all supported stable versions and removed in a later release. They are also flagged through Dev Dashboard alerts, warnings in the GraphiQL explorer, the developer changelog and emails to the app’s emergency developer contact. Make sure that contact address reaches someone who still works with you.
3. Fix deprecations before you change the version
Update the code that uses deprecated fields while still on the current version, where the replacement already exists. Then the version change itself becomes a small step. If the app still uses the REST Admin API, a version upgrade is a natural moment to plan that move; our REST to GraphQL migration guide covers it.
4. Test against the new version
- Point a development store or test environment at the new version.
- Run the app’s main jobs end to end: the sync, the import, the screen your team opens every morning.
- Send test webhooks and confirm the handlers parse the new payloads.
- Compare outputs with the old version for a sample of real records: totals, money fields, dates, statuses.
- For GraphQL, check
errorsanduserErrorsin responses, not only the HTTP status.
Testing against the release candidate early gives you more time, but Shopify notes that a release candidate may include backwards-incompatible changes and is not recommended for production, so test again on the stable version before you deploy.
5. Deploy, then watch
Change the version in one place, deploy, and watch for a few days:
- error rates and failed requests in your logs, or the app’s Overview and Logs in the Dev Dashboard;
- webhook failures, since Shopify removes a subscription created through the Admin API after 8 consecutive failed deliveries;
- the
X-Shopify-API-Versionheader, which should now match the new version; - the daily totals your team relies on.
Update the app’s webhook api_version in the same release, or in a planned follow-up, and redeploy extensions pinned to old versions.
6. Record it
Add a line to the app’s runbook: date, old and new version, what changed, who tested it, and the date the new version stops being supported. That date becomes the deadline for the next check.
A one-page version tracker
Keep this table for every custom app and integration you run:
| App | Admin API version | Webhook version | Supported until | Owner | Last checked |
|---|---|---|---|---|---|
| Order sync to warehouse | 2026-07 | 2026-07 | see versioning page | ops lead | Oct 2026 |
| Product import | 2026-04 | 2026-01 | see versioning page | developer | Oct 2026 |
The versioning page lists the date each version stays accessible. Copy it in rather than estimating it.
What happens if you skip a year
Nothing visible, at first. Once the version expires, requests fall forward to the oldest accessible version, and the app runs against changes it was never tested on. Removed fields can return errors, changed defaults can alter results, and a sync can look healthy while it writes the wrong thing.
Shopify’s help center tells merchants to forward warnings about unsupported custom apps to the app developer as soon as they get them. If those emails land in an inbox nobody reads, nobody acts on them. Our guide to maintaining a custom Shopify app covers who should own these warnings and the rest of the upkeep, and integrations that don’t break shows how to make a quiet failure loud.
Before you upgrade an old admin-created app
If your app was created in the Shopify admin before January 1, 2026, it still works and is managed as a legacy custom app. Version upgrades are a good time to decide whether it should move to the Dev Dashboard; creating a custom app in the Dev Dashboard explains what that involves and why you should not delete the old app first.
Having it done for you
If no one on your side has time to run this every quarter, it can be part of someone’s job outside your team. Our custom solutions page describes the Shopify work we take on; the same team builds and runs Storefleet Store Ops. Our guides to what a custom Shopify app costs and hiring a Shopify app developer help you decide how to cover upkeep.
FAQ
How often does Shopify release a new API version?
Every three months, on January 1, April 1, July 1 and October 1 at 5pm UTC. Each stable version is supported for at least 12 months.
What happens when my app calls an unsupported API version?
Shopify falls forward and responds using the oldest accessible stable version. Requests keep succeeding, but the app now runs on a version it was not tested against. The X-Shopify-API-Version response header shows which version was used.
How do I check which API version my custom app uses?
Look for the version in the request URLs or client settings, log the X-Shopify-API-Version response header, and for Dev Dashboard apps open a request in the app’s Logs. The Deprecated API calls endpoint lists a custom app’s deprecated calls from the past 30 days.
Should I upgrade every quarter or once a year?
Shopify recommends updating to the latest stable version each quarter. Upgrading once a year can work, since each version is supported for at least 12 months, but each jump then covers more release notes and more risk.
Do webhooks have their own API version?
Yes. The api_version under [webhooks] in shopify.app.toml sets how payloads are serialized for app-specific subscriptions, and each HTTPS delivery includes the version in the X-Shopify-API-Version header. Upgrade it alongside your API calls.