shopify-upgrade

What it does

Shopify ships a new API version every quarter and supports each one for about a year, so upgrading is a recurring tax rather than a one-off project. This skill treats it as a migration with a proof obligation, not a find-and-replace.

It starts by finding what your codebase actually pins — which is usually more than you think. Detection is deliberately language-agnostic: a Shopify version is always YYYY-MM with the month in {01, 04, 07, 10}, so a single sweep catches a TypeScript constant, a TOML key, a .env value, a Python positional argument, and a raw URL string hardcoded in one webhook handler, across JS/TS, PHP, Python, Ruby, Go, .NET or anything speaking raw HTTP. A repo running four different versions across Admin, Storefront, webhooks and Functions is the normal case, and the plan prices each one separately instead of quietly normalising them.

Then it establishes what actually breaks. Every claim traces to something fetched that day — each operation validated against the target version’s schema through Shopify’s own Dev MCP, plus the versioned docs and the full changelog archive. Model recall of which fields exist in a given Shopify version is training data, stale by construction, and it never announces itself as wrong. So it isn’t used: a call site with no sourced ledger row doesn’t get edited at all.

When to use it

When you’re several versions behind and need to know the blast radius before committing to the work. When a deprecation notice or a sunset email lands and you need to find out whether it touches you. When X-Shopify-API-Deprecated-Reason starts showing up in your response headers. When you want to migrate legacy Admin REST calls to GraphQL and want the GID, error-model and rate-limit traps handled deliberately rather than discovered in production. Or just to answer “which Shopify version are we even on?” — a question with a surprisingly long answer in most repos.

“Tell me what breaks, don’t change anything” is a complete, supported run: it stops at the plan, and the plan is the deliverable.

What you get

• A real surface inventory — every version pin with its file and line, each SDK’s implicit default resolved (the version that silently moves when someone bumps a dependency), and an explicit row for every surface, including the ones marked “not present” so an absent row is never confused with an overlooked one.
• A change ledger, one row per affected call site — what it uses, its fate in the target version, and the source URL with a fetch date. Deprecation reasons are quoted verbatim from the versioned docs, because that text usually names the replacement — and they are looked up deliberately, because a query can validate cleanly and still be selecting a field that’s on its way out. Nothing is edited without a row.
• A risk-tiered plan you approve before any file changes — BREAKING (fails at runtime), BEHAVIOR (same shape, different result), DEPRECATED (with its removal version, so accepting it as debt is a real choice), SCOPE, and OPPORTUNITY. Opportunities stay opt-in: an upgrade PR that also refactors is a PR nobody can review.
• Access-scope changes surfaced as their own tier — a newly required scope means every already-installed merchant must re-authorise. It works perfectly in dev and fails for every existing customer, so it’s reported as an operational event with a comms note, never buried in a table of file paths.
• A specialist agent per surface, run in parallel — Admin GraphQL, Admin REST (including REST→GraphQL when you approve it), Storefront and Customer Account, Hydrogen, Functions, App Bridge and UI extensions, Liquid themes. Each loads only its own playbook and validates its own output against the target version before reporting done.
• Honest partial upgrades — a surface with an unresolved breaking finding stays on its old version and says so. A partial upgrade you can see beats a complete one that fails at 2am with a clean git history.
• Verification that outlives the diff — the codebase is re-swept for stale version literals (the config constant is easy; the hardcoded URL is what gets missed), GraphQL and Liquid are validated at the target version, and the build runs. Whatever couldn’t be verified is named as unverified rather than implied as passing.
• Two zero-dependency scripts you can read before installing — one finds version pins in any language, one filters the ~780-entry changelog by status, surface and date. Neither makes a network call: you fetch, they parse.