gabrielmoreira 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
}
}