Shopify Migration Plugin

A comprehensive plugin for migrating products, collections, tags, and product types from Shopify to Medusa.

Overview

This plugin provides seamless integration with Shopify, enabling you to migrate your entire product catalog from a Shopify storefront to your Medusa store. It supports custom product properties and extended data models to preserve Shopify-specific information during migration.

Features

• Complete Product Migration - Import products, variants, collections, tags, and product types from Shopify
• Extended Data Models - Custom models for preserving Shopify-specific data:
  • product_extended - Vendor information and custom product properties
  • product_variant_extended - Shipping requirements and variant-specific data
• Admin API Endpoints - RESTful API for managing migrations and custom properties
• Admin UI Widgets - Display extended product information in the Medusa admin
• Custom Property Filtering - Filter products by custom properties through dedicated endpoints
• Development Mode - Automatic plugin rebuilding during development
• MedusaJS v2 Compatible - Built for Medusa v2 architecture

Requirements

• MedusaJS v2
• Node.js 20 or higher
• Active Shopify store with API access
• Database with migration support

Installation

Install the plugin using npm:

npm install @gfed-mds/medusa-plugin-shopify

Configuration

Environment Variables

Add your Shopify store URL to your .env file:

SHOPIFY_BASE_URL=https://your-store.myshopify.com
SHOPIFY_API_KEY=your_shopify_api_key
SHOPIFY_API_SECRET=your_shopify_api_secret
SHOPIFY_ACCESS_TOKEN=your_shopify_access_token

Plugin Configuration

Add the plugin to your medusa-config.js:

const plugins = [
  // ... other plugins
  {
    resolve: "@gfed-mds/medusa-plugin-shopify",
    options: {
      shopify_base_url: process.env.SHOPIFY_BASE_URL,
      api_key: process.env.SHOPIFY_API_KEY,
      api_secret: process.env.SHOPIFY_API_SECRET,
      access_token: process.env.SHOPIFY_ACCESS_TOKEN,
    },
  },
]

Database Migration

Run database migrations to create the extended data models:

npx medusa migrations run

Usage

Migrating Products from Shopify

Use the migration API endpoint to import products:

POST /admin/shopify-plugin/migrate

This endpoint will:

1. Connect to your Shopify store
2. Fetch all products, variants, collections, and tags
3. Import them into your Medusa database
4. Create extended product records with Shopify-specific data

Managing Custom Properties

The plugin provides API routes for managing custom product properties:

# Get products with custom properties
GET /admin/shopify-plugin/products

# Filter products by custom properties
GET /admin/shopify-plugin/products?vendor=YourVendor

# Get product extended data
GET /admin/shopify-plugin/products/:id/extended

Admin UI Integration

The plugin includes admin UI widgets that display:

• Vendor information
• Custom product properties
• Shipping requirements
• Extended variant data

Extended Data Models

Product Extended

Stores Shopify-specific product information:

• Vendor name
• Product source
• Custom metadata
• Additional product properties

Product Variant Extended

Stores variant-specific data:

• Shipping requirements
• Weight and dimensions
• Fulfillment settings
• Custom variant properties

Migration Best Practices

1. Backup Your Data - Always backup your Medusa database before migration
2. Test First - Run migration on a development environment first
3. Verify Data - Check that all products, variants, and collections migrated correctly
4. Custom Fields - Review extended data to ensure Shopify-specific information is preserved
5. Images - Verify that product images are properly imported

Shopify Data Preserved

The plugin preserves the following Shopify data:

• Products and product variants
• Collections and collection memberships
• Product tags
• Product types
• Vendor information
• Product options
• Variant options
• Custom product properties
• Shipping requirements

API Endpoints

Migration

• POST /admin/shopify-plugin/migrate - Start product migration from Shopify

Product Management

• GET /admin/shopify-plugin/products - List products with extended data
• GET /admin/shopify-plugin/products/:id - Get product with extended data
• GET /admin/shopify-plugin/products/:id/extended - Get extended product data only

Links

• Shopify API Documentation
• MedusaJS Documentation