Shopify Upgrade & Migration

Overview

Guide for upgrading Shopify API versions (quarterly releases) and migrating from the legacy REST Admin API to the GraphQL Admin API. REST was deprecated as a legacy API on October 1, 2024.

Prerequisites

Current Shopify API version identified
Git for version control
Test suite available
Access to Shopify release notes

Instructions

Step 1: Check Current Version and Available Versions

# Check what API version you're using in code
grep -r "apiVersion" src/ --include="*.ts" --include="*.js"
grep -r "api_version" . --include="*.toml"

# Check what versions the store supports
curl -s -H "X-Shopify-Access-Token: $TOKEN" \
  "https://$STORE/admin/api/versions.json" \
  | jq '.supported_versions[] | {handle, display_name, supported, latest}'

Shopify releases quarterly (e.g., 2025-01, 2025-04, 2025-07, 2025-10). Versions are supported for ~12 months after release.

Step 2: Review Breaking Changes

Key breaking changes by version:

Version	Breaking Change	Migration
2024-10	`ProductInput` split into `ProductCreateInput` + `ProductUpdateInput`	Update mutations to use separate types
2024-10	REST declared legacy	Migrate to GraphQL Admin API
2024-07	`InventoryItem.unitCost` removed	Use `InventoryItem.unitCost` on `InventoryLevel`
2024-04	Cart warnings replace inventory userErrors (Storefront)	Update cart error handling
2025-01	New public apps must use GraphQL only	No REST for new public apps

Step 3: Migrate REST to GraphQL

Side-by-side comparison of REST vs GraphQL patterns, plus a mapping table for common endpoints (products, orders, customers, webhooks).

See REST to GraphQL Migration for the complete examples and mapping table.

Step 4: Update API Version in Config

// src/shopify.ts — use LATEST_API_VERSION instead of hardcoded dates
import { LATEST_API_VERSION } from "@shopify/shopify-api";

const shopify = shopifyApi({
  apiKey: process.env.SHOPIFY_API_KEY!,
  apiSecretKey: process.env.SHOPIFY_API_SECRET!,
  hostName: process.env.SHOPIFY_HOST_NAME!,
  apiVersion: LATEST_API_VERSION,
  // ...
});

# shopify.app.toml
[webhooks]
api_version = "2025-04"  # Update quarterly

Step 5: Handle the ProductInput Split (2024-10)

In API version 2024-10, Shopify split the single ProductInput type into ProductCreateInput and ProductUpdateInput. All product mutations need updating.

See ProductInput Split for before/after examples.

Output

API version updated across all config files
REST endpoints migrated to GraphQL equivalents
Breaking changes addressed
Test suite passing on new version

Error Handling

Error	Cause	Solution
`API version unsupported`	Version too old	Check supported versions endpoint
`Field not found in type`	Field renamed/removed in new version	Check release notes for migration
`ProductInput is not defined`	Using old type on 2024-10+	Use `ProductCreateInput` / `ProductUpdateInput`
`REST API 410 Gone`	Endpoint removed	Migrate to GraphQL equivalent

Examples

API Version Upgrade Script

#!/bin/bash
OLD_VERSION="2024-10"
NEW_VERSION="2025-04"

echo "Upgrading Shopify API from $OLD_VERSION to $NEW_VERSION"

# Find all files referencing old version
echo "Files to update:"
grep -rn "$OLD_VERSION" . --include="*.ts" --include="*.js" --include="*.toml" --include="*.json"

# Replace (review diff before committing)
find . -type f \( -name "*.ts" -o -name "*.js" -o -name "*.toml" \) \
  -exec sed -i "s/$OLD_VERSION/$NEW_VERSION/g" {} +

echo "Updated. Run tests: npm test"

Deprecation Monitor

// Log deprecation warnings from Shopify response headers
function checkDeprecationHeaders(headers: Headers): void {
  const sunset = headers.get("x-shopify-api-deprecated-reason");
  if (sunset) {
    console.warn(`[SHOPIFY DEPRECATION] ${sunset}`);
    // Alert your team
  }
}

shopify-upgrade-migration