Shopify Migration Deep Dive Skill

Shopify Migration Deep Dive

Overview

Migrate product catalogs, customers, and orders to Shopify using the GraphQL Admin API bulk mutations, CSV imports, and incremental migration patterns.

Prerequisites

Source platform data exported (CSV, JSON, or API access)
Shopify store with appropriate access scopes
Scopes needed: write_products, write_customers, write_orders, write_inventory

Instructions

Step 1: Assess Migration Scope

| Data Type | Shopify Import Method | Complexity | |-----------|----------------------|------------| | Products + variants | productSet mutation (upsert) | Low | | Product images | productCreateMedia mutation | Low | | Customers | Customer CSV import or customerCreate | Medium | | Historical orders | draftOrderCreate + draftOrderComplete | High | | Inventory levels | inventorySetQuantities mutation | Medium | | Collections | collectionCreate mutation | Low | | Redirects (URLs) | urlRedirectCreate mutation | Low | | Metafields | Included in product/customer mutations | Medium |

Step 2: Bulk Product Import with productSet

productSet is idempotent — it creates or updates based on handle, making it perfect for migrations. Handles variants, metafields, and all product attributes in a single mutation.

See Product Set Migration for the complete migration function.

Step 3: Bulk Operations for Large Imports

For importing thousands of products, use Shopify's staged uploads combined with bulk mutation to avoid rate limit issues.

See Bulk Operations Import for the staged upload and bulk mutation workflow.

Step 4: Set Inventory Levels & URL Redirects

After products are created, set inventory quantities at each location and create URL redirects to preserve SEO from the old platform.

See Inventory and Redirects for both mutation implementations.

Step 5: Post-Migration Validation

Automated validation that compares expected source counts against actual Shopify counts for products, customers, and other data types.

See Post-Migration Validation for the validation script.

Output

Products migrated with variants, images, and metafields
Inventory levels set at correct locations
URL redirects preserving SEO
Migration validated against source counts

Error Handling

| Issue | Cause | Solution | |-------|-------|----------| | TAKEN on product handle | Duplicate handle | Append suffix or use productSet for upsert | | Rate limited during import | Too many sequential calls | Use bulk operations or add delays | | Image upload fails | URL not publicly accessible | Use staged uploads for private images | | Inventory not updating | Wrong inventoryItemId | Query variant's inventoryItem.id first |

Examples

Quick Migration Status

# Count products in source vs Shopify
echo "Shopify product count:"
curl -sf -H "X-Shopify-Access-Token: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ productsCount { count } }"}' \
  "https://$STORE/admin/api/${SHOPIFY_API_VERSION:-2025-04}/graphql.json" \
  | jq '.data.productsCount.count'

Agent Skills: Shopify Migration Deep Dive

Install this agent skill to your local

Skill Files