---
name: shopify-upgrade-migration
description: |
  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".
allowed-tools: Read, Write, Edit, Bash(npm:*), Bash(curl:*)
version: 1.0.0
license: MIT
author: Jeremy Longshore <jeremy@intentsolutions.io>
tags: [saas, ecommerce, shopify]
compatible-with: claude-code
---

# 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

```bash
# 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](references/rest-to-graphql-migration.md) for the complete examples and mapping table.

### Step 4: Update API Version in Config

```typescript
// 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,
  // ...
});
```

```toml
# 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](references/product-input-split.md) 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

```bash
#!/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

```typescript
// 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](https://shopify.dev/docs/api/release-notes)
- [Migrate REST to GraphQL](https://shopify.dev/docs/apps/build/graphql/migrate/learn-how)
- [API Versioning Guide](https://shopify.dev/docs/api/usage/versioning)