Skills Development Shopify API Migration And Versioning

Shopify API Migration And Versioning

v20260423
shopify-upgrade-migration
This guide provides comprehensive steps for upgrading Shopify API versions (quarterly releases) and migrating your application from the legacy REST Admin API to the modern GraphQL Admin API. It details how to check supported versions, identify breaking changes (like ProductInput splits), and update configurations, ensuring your codebase remains current with Shopify's evolving API standards.
Get Skill
379 downloads
Overview

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:

VersionBreaking ChangeMigration
2024-10ProductInput split into ProductCreateInput + ProductUpdateInputUpdate mutations to use separate types
2024-10REST declared legacyMigrate to GraphQL Admin API
2024-07InventoryItem.unitCost removedUse InventoryItem.unitCost on InventoryLevel
2024-04Cart warnings replace inventory userErrors (Storefront)Update cart error handling
2025-01New public apps must use GraphQL onlyNo 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

ErrorCauseSolution
API version unsupportedVersion too oldCheck supported versions endpoint
Field not found in typeField renamed/removed in new versionCheck release notes for migration
ProductInput is not definedUsing old type on 2024-10+Use ProductCreateInput / ProductUpdateInput
REST API 410 GoneEndpoint removedMigrate 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
  }
}

Resources

Info
Category Development
Name shopify-upgrade-migration
Version v20260423
Size 3.6KB
Updated At 2026-04-28
Language