Upgrade Shopify API versions and migrate from REST to GraphQL with breaking change detection. Use when upgrading API versions, migrating from deprecated REST endpoints, or handling Shopify's quarterly API release cycle. Trigger with phrases like "upgrade shopify", "shopify API version", "shopify breaking changes", "migrate REST to GraphQL", "shopify deprecation".
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.
# 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.
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 |
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.
// 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
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.
| 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 |
#!/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"
// 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
}
}