shopify-upgrade-migration

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: 2024-01, 2024-04, 2024-07, 2024-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

// BEFORE: REST Admin API
const restClient = new shopify.clients.Rest({ session });
const { body } = await restClient.get({
  path: "products",
  query: { limit: 50, status: "active" },
});
const products = body.products;

// AFTER: GraphQL Admin API
const graphqlClient = new shopify.clients.Graphql({ session });
const response = await graphqlClient.request(`{
  products(first: 50, query: "status:active") {
    edges {
      node {
        id
        title
        status
        variants(first: 10) {
          edges { node { id price sku } }
        }
      }
    }
    pageInfo { hasNextPage endCursor }
  }
}`);
const products = response.data.products.edges.map((e: any) => e.node);

Common REST-to-GraphQL mappings:

REST Endpoint	GraphQL Query/Mutation
GET /products.json	query { products(first: N) { edges { node { ... } } } }
POST /products.json	mutation { productCreate(product: $input) { ... } }
PUT /products/{id}.json	mutation { productUpdate(product: $input) { ... } }
GET /orders.json	query { orders(first: N) { edges { node { ... } } } }
GET /customers/{id}.json	query { customer(id: $id) { ... } }
POST /webhooks.json	mutation { webhookSubscriptionCreate(...) { ... } }

Step 4: Update API Version in Config

// src/shopify.ts — update the version
const shopify = shopifyApi({
  apiKey: process.env.SHOPIFY_API_KEY!,
  apiSecretKey: process.env.SHOPIFY_API_SECRET!,
  hostName: process.env.SHOPIFY_HOST_NAME!,
  apiVersion: "2024-10", // <-- update this
  // ...
});

# shopify.app.toml
[webhooks]
api_version = "2024-10"  # Update here too

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

// BEFORE (pre-2024-10): single ProductInput for create AND update
const OLD_CREATE = `
  mutation($input: ProductInput!) {
    productCreate(input: $input) { ... }
  }
`;

// AFTER (2024-10+): separate types
const NEW_CREATE = `
  mutation($input: ProductCreateInput!) {
    productCreate(product: $input) {
      product { id title }
      userErrors { field message }
    }
  }
`;

const NEW_UPDATE = `
  mutation($input: ProductUpdateInput!) {
    productUpdate(product: $input) {
      product { id title }
      userErrors { field message }
    }
  }
`;

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-04"
NEW_VERSION="2024-10"

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

• Shopify API Release Notes
• 2024-10 Release Notes
• Migrate REST to GraphQL
• API Versioning Guide

Next Steps

For CI integration during upgrades, see shopify-ci-integration.