shopify-upgrade-migration

What this skill does

# 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)