Skip to content
Tutorials Center
My learning

Topics

Lesson 13 of 55 ยท Admin GraphQL API

API Versioning and Deprecations

Learn how Shopify's quarterly Admin API versions work: the support window, release candidates, the version in the URL, deprecations and an upgrade checklist.

Shopify changes its APIs all the time: new fields appear, old ones are renamed, and a few are removed. If every change hit every app at once, apps would break on random Tuesdays. To avoid that, Shopify versions its APIs. You pick a version, your requests behave the same way for as long as that version is supported, and you move to a newer one on your own schedule.

This lesson explains how the Admin GraphQL API versions are named and released, how long each one lives, what happens when you ask for a version that is gone, and how to keep an app current without panic upgrades. It builds on GraphQL for Shopify Developers.

Shopify's exact rules (dates, support length, the contents of each version) are published in its developer documentation and do change over time. The examples here use the stable version 2026-07 as a stand-in for "a recent version". Always check the current list before copying a version string into a real app.

How versions are named and released

Versions are named by year and month: 2026-01, 2026-04, 2026-07, 2026-10. A new stable version is released every three months, on the first day of January, April, July and October. Each stable version is supported for at least twelve months after its release. That means at any moment you normally have four stable versions to choose from, plus two special ones:

Name Meaning
2026-07 (a dated version) Stable. Frozen, supported for at least 12 months. Use this in production.
2026-10 before its release date Release candidate (RC). A preview of the next stable version. Good for testing upgrades early; do not ship it.
unstable The moving target. It changes without notice and has no support promise. Only for trying brand-new features.

Version stability applies to the API surface: the fields, arguments, enum values and behavior of the version you named. A field that exists in 2026-07 keeps working in 2026-07 for its whole lifetime, even if a newer version removes it.

flowchart LR
    RC["Release candidate<br/>before release day"] --> S["Stable version<br/>12+ months of support"]
    S --> N["Newer versions arrive<br/>every 3 months"]
    S --> E["Support ends<br/>about a year later"]
    E --> F["Requests fall forward<br/>to the oldest supported"]

Each new version arrives every three months, and the oldest supported one retires about a year after its release.

The version lives in the URL

You choose the version for each request by putting it in the endpoint path. The Admin GraphQL API is served from the shop's own domain:

TEXT
POST https://{shop}.myshopify.com/admin/api/2026-07/graphql.json
X-Shopify-Access-Token: {access token}
Content-Type: application/json

Because the version is part of the path, one app can even call different versions for different requests. The response includes an X-Shopify-API-Version header that tells you which version actually served the request. Log it. It is the quickest way to notice that you are not on the version you think you are.

In an app built from the Shopify CLI template, you rarely type the URL yourself: the app library takes an apiVersion setting once (in the code that configures the Shopify app object) and the admin client builds URLs from it. Webhooks have their own version setting, in the app configuration file (api_version under the webhooks section), which you will meet in App Configuration with shopify.app.toml. Keep both in step, otherwise a webhook payload and your API queries may disagree about field names.

Do not write the version into your code in twenty places. Keep it in one constant or configuration value. An upgrade then becomes a one-line change plus testing, instead of a search-and-replace hunt.

What happens when a version is not supported

If you request a version that has passed its end of support, Shopify does not return an error. It falls forward: the request is served by the oldest version that is still supported. This is friendly, but it is also a trap. Your app can suddenly run against an API that has removed a field you rely on, and you only notice because queries start failing.

The same applies if you call a version that does not exist. Instead of a clean failure you get a different version than you wrote. The lesson is simple: never rely on fall-forward as a plan. Upgrade while the version you use is still supported.

Deprecations

Within a stable version nothing is removed. Deprecation happens between versions:

  1. A field, argument or mutation is marked @deprecated with a reason that often names the replacement.
  2. The deprecated item keeps working in every version that already had it.
  3. A later version no longer contains it. When your pinned version retires, the removal reaches you.

You can see deprecations in your tooling: introspection and the GraphiQL explorer show deprecated fields as struck through, and the GraphQL reference lists them per version. Query results can also carry hints. Make it a habit to run your queries against the next release candidate in a development store. Errors there are an early warning, three months ahead of the real change.

A runnable version-window calculator

The first stand-in encodes the rules above as plain JavaScript: it builds the list of quarterly versions, adds twelve months of support, and classifies each one for a fixed "today". It is not Shopify's code. It is a model of the stated rules, so the dates would be wrong if Shopify changed its policy, and the real platform is always the authority.

JS Which versions are supported today?

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Run it and read the output: on that date four versions are supported and 2027-01 is still an upcoming release. Change the today line to a date a few months later and watch the oldest version drop out. That is exactly the slow rolling window you should keep in your head.

Resolving a requested version

The second stand-in models the fall-forward behavior and adds an upgrade-planning check: how many days remain before the versions an app uses stop being supported?

JS Fall-forward and days left

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The request for 2025-04 quietly became 2026-01. Your code never saw an error, which is why logging the response header matters.

An upgrade checklist

A calm, repeatable routine beats a late-night scramble. Aim to upgrade once per quarter, shortly after each stable release.

  1. Read the release notes for the new version and note anything you use that changed.
  2. Create a branch and change the one version constant.
  3. Run your test suite, including the tests that use a stub client (Testing Shopify Apps).
  4. Run every query and mutation against a development store with the new version. Look for new errors entries and for userErrors that were not there before.
  5. Update the webhook api_version and deploy a new app version, then watch real deliveries for payload differences.
  6. Deploy, and confirm in logs that X-Shopify-API-Version shows the version you expect.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. How often does Shopify release a new stable Admin API version?

    Stable versions are named by year and month and arrive quarterly, in January, April, July and October.
  2. 2. What happens if you call a version that is past its end of support?

    Shopify falls forward to the oldest supported version. That can remove fields you rely on, so upgrade before support ends.
  3. 3. Where does a request choose its Admin API version?

    The version is part of the endpoint path. The X-Shopify-API-Version response header tells you what actually served the call.
  4. 4. When should you use the unstable version?

    Unstable changes without notice and has no support promise, so it is for experiments only.

Summary

  • Admin API versions are named YYYY-MM and released quarterly; each is supported for at least twelve months.
  • A release candidate previews the next stable version, and unstable is only for experiments.
  • The version is in the URL path, and the X-Shopify-API-Version header shows what served the call.
  • Unsupported versions fall forward to the oldest supported one, which can break your queries silently.
  • Deprecations happen between versions, never inside one; keep the version in one place and upgrade every quarter.

Next, put a version to work by reading real data in Querying Products and Variants.