Shopify Upgrade Guard

Find evidence-backed Shopify API and platform migration risks against a target version.

RexCode Open Source · Shopify developer tools

Shopify Upgrade Guard scans local application source and configuration for documented API removals, deprecations and platform changes. Each finding includes a version boundary and an official source where available.

Features

• Checks migration risks against an explicit Shopify API target.
• Separates current debt from target-version findings.
• Supports JSON and SARIF output, baselines and pull-request-only findings.
• Keeps rules deterministic and links Shopify-specific checks to official evidence.

Install and run

Requires Node.js 22 or later.

npm install --save-dev shopify-upgrade-guard
npx shopify-upgrade-guard scan --target 2026-10

Use npx shopify-upgrade-guard --help for all commands. See the CLI guide and version model.

GitHub Action

Pin the v0.5.0 release tag for the UG-TAX-001 rule. The repository ruleset prevents released semantic version tags from being changed or deleted:

name: Check Shopify API migration
on: [pull_request]
permissions:
  contents: read

jobs:
  upgrade-guard:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          fetch-depth: 0
      - uses: RexCode-Digital/[email protected] # v0.5.0
        with:
          target: 2026-10
          fail-on: warning

Inputs are target, fail-on, fail-on-new, base-ref and path. Outputs include active/new/resolved finding counts, error count, version inventory, policy outcome and JSON results. See action.yml.

Example output

Shopify Upgrade Guard
Target version: 2026-10
Files scanned: 1

ERROR  UG-CUSTOMER-001
Customer Account checkout types are removed
  customer.graphql:1
  This usage is affected by target 2026-10.
  Migration: Use Storefront cart flows or Customer.orders as appropriate.
  Source: https://shopify.dev/changelog/customer-account-api-last-incomplete-checkout-and-checkout-types-removed

1 active risk found
Result: migration recommended

The example is shortened from a scan of a synthetic GraphQL document.

Supported capabilities and evidence

Rules cover documented Shopify API and platform lifecycle changes across supported Admin GraphQL, Customer Account, Checkout UI, POS, extension-configuration and other tracked surfaces. Each rule defines its affected version and migration guidance; the CLI guide, generated rule catalogue from the rules command, and migration documentation describe current coverage. Rules only apply at their documented version boundary.

Version 0.5.0 adds UG-TAX-001 for an explicit tax_summaries/create subscription when the selected target is 2027-01 or later. It reports a review warning; it cannot determine whether the handler already accepts Global IDs. See the 2027-01 research and limits.

Limitations and privacy

Scans are offline and do not call Shopify or execute application code. A match is a review signal, not proof of a production failure. Static detection cannot see runtime-generated operations, every framework wrapper, live subscription configuration or whether application code already handles a changed payload. Review the linked source and test the migration in your application.

Documentation

• Getting started
• CLI and rule behaviour
• Configuration and baselines
• 2027-01 migration research
• Release process

Related RexCode OSS tools

• ChangeGuard reviews semantic app configuration changes.
• Shopify Scope Guard checks requested access scopes against static evidence.
• Shopify App Review Guard reports App Store and production-readiness evidence.

Use the four-tool workflow to run the published Actions together.

Contributing and support

Read CONTRIBUTING.md and the RexCode Open Source standards. For usage questions or safe reproductions, use SUPPORT.md or the issue tracker.

Security

Use SECURITY.md for private vulnerability reporting. Do not post credentials, merchant data or private source in public issues.

Licence and affiliation

MIT licensed. Shopify's names and marks belong to Shopify. This independent open-source project is not affiliated with, endorsed by, or certified by Shopify.