When Shopify retires an API version

Every few months a merchant notices the same thing: an app that worked fine yesterday has started logging errors, and nobody can say why. There is usually no announcement. There is no email. The app just starts failing, quietly, on the operations that mattered.

The reason is almost always the same, and it has nothing to do with the app losing interest.

Shopify versions things on a calendar

Shopify publishes a new version of its APIs four times a year — one per quarter. Each version is named for the quarter it shipped in: 2025-01, 2025-04, 2025-07, and so on. Each one is supported for at least a year before it is retired.

That retirement is the part that catches people. When a version is retired, requests made against it stop being served. Not deprecated with a warning. Not thinned out. The endpoint is gone, and every integration pinned to that version starts returning errors on its next call.

An app that hard-codes a version has therefore bought itself a fuse. It works perfectly until a Tuesday.

The mistake is the version pin, not the version

This is worth separating, because they get confused. Pinning an API version is not negligence. The version is the contract; you should target a specific one. The mistake is targeting one and never returning.

The failure mode looks like this:

  March          You build against 2025-01. It works. Ship it.
  April          2025-04 ships. Nothing breaks. You relax.
  ...
  March next yr  2025-01 hits end of support.
                 Every request fails.
                 Someone reports it as "the app is broken."

A year of silence, then a cliff. The app did not rot — it was never on a migration schedule, so the retirement date arrived like an event rather than like a release.

The difference is entirely in whether the version bump was scheduled work or an incident. That is why a maintained app publishes release notes for a migration the way it publishes them for a feature. It is the same category of change: something shipped.

What the failure actually looks like

The symptoms are recognisable once you know them:

Where you see it	What it looks like
App settings page	A banner about an unsupported version
App logs	404 or 400 on endpoints that worked before
Store front	A section that silently stops updating
Sync jobs	Records that stop moving with no error surfaced to a human

The nasty one is the fourth. A background job that fails on every retry is easy to miss, because nothing in the merchant’s day looks broken. Orders still come in. The store still looks fine. The inventory is just quietly wrong now, and nobody connects it to a version retired eight weeks ago.

How to check what your apps are on

Two places, and the second one is the one that actually tells you anything.

In the app itself. Most apps show their API version somewhere in settings. Some are conscientious about it. Some are not.

In the Shopify admin, under Settings → Apps and sales channels. Each installed app’s detail page shows a compatibility indicator when the app is behind the store’s current version. This is the check that catches you, because it is the merchant’s own view and it does not depend on the app choosing to disclose.

Go through the list today. Not because something is broken — because the value of knowing is entirely in knowing it before something is broken. The list of apps you did not know you had installed is usually the interesting part.

What to do about it

If an app is behind, you have three options, in this order:

1. Open a support ticket with the app. Most maintainers will migrate. This is ordinary, scheduled work for anyone competent, and it is a normal thing to ask for.
2. If the app is unresponsive or unlisted, look for a replacement. Search the App Store for the problem rather than the product. An app that has not shipped in a year is very likely one version behind too.
3. If the problem is core enough that you keep circling back to it, that is the signal to build something. See app, theme app, or custom app for how to decide which one that is.

The thing worth noticing

Almost nobody markets maintenance. It is invisible when it is working, which is exactly the property that makes it valuable and exactly the property that makes it get skipped.

If you want a running example of what a maintained app looks like, this site’s changelog is one. It is a cross-app release feed, and API migrations appear in it as ordinary lines — dated, versioned, described in a sentence — because that is what they are. Nothing about a migration is an emergency worth emailing anyone about, provided someone scheduled it.