Commerce Migrate
A general-purpose migration framework for bringing store information into Drupal Commerce from various e-commerce platforms.
commerce_migrate
Install
composer require 'drupal/commerce_migrate:^4.0'
Overview
Commerce Migrate is a comprehensive migration framework that extends the Drupal Migrate module to facilitate migration from various e-commerce platforms to Drupal Commerce 2. It provides the necessary plugins, source handlers, process plugins, and destination plugins to migrate products, orders, customers, payments, and other commerce data.
The module includes submodules for migrating from Drupal Commerce 1.x, Ubercart (both Drupal 6 and 7), Magento 2, Shopify, and WooCommerce. Each submodule provides specialized source plugins that read data from the source platform and process plugins that transform the data for Drupal Commerce 2 entities.
When using core's Migrate Drupal UI interface or Migrate Upgrade module, Commerce 1.x and Ubercart configurations and data are automatically upgraded to Commerce 2. For CSV-based sources like Magento, Shopify, and WooCommerce, the module provides example migrations that can be customized.
Features
- Migrate products, product variations, and product types from legacy e-commerce platforms
- Migrate orders, order items, and order adjustments with proper state mapping
- Migrate customer profiles and billing/shipping addresses
- Migrate payment transactions and payment gateways
- Migrate product attributes and attribute values
- Migrate tax types and shipping rates
- Support for database-to-database migration from Commerce 1.x and Ubercart
- Support for CSV-based migrations from Magento 2, Shopify, and WooCommerce
- Automatic integration with Drupal's Migrate Drupal UI for seamless upgrades
- Event subscribers to properly handle rollbacks while preserving related entities
- Process plugins for converting price formats between different currency representations
- Destination plugins for creating Commerce product types with required fields
- Field migration plugins for Commerce-specific field types like commerce_price
Use Cases
Upgrading from Drupal 7 Commerce Kickstart
Migrate a complete Commerce Kickstart 2 site to Drupal Commerce 2. The commerce_migrate_commerce submodule handles all aspects including products, orders, customers, payments, and configuration. Enable the submodule, configure the source database connection, and use Migrate Drupal UI or Drush to run migrations.
Migrating from Ubercart to Drupal Commerce
Upgrade an existing Ubercart store (Drupal 6 or 7) to Drupal Commerce 2. Products that were nodes in Ubercart become proper Commerce products with variations. Orders, customers, and payments are migrated with state mappings appropriate for Commerce 2's workflow.
Importing products from Magento
Export products and categories from a Magento 2 store as CSV files, then use the commerce_migrate_magento submodule as a template to create custom migrations. Includes handling for product images, categories, and user profiles.
Migrating from Shopify to Drupal Commerce
Export product data from Shopify as CSV files, then use the commerce_migrate_shopify submodule migrations to import products, variations, and taxonomy terms into Drupal Commerce.
Custom CSV product import
Use the commerce_migrate_csv_example submodule as a starting point to create custom migrations for importing products from spreadsheets. The example demonstrates importing taxonomy terms, attribute values, images, product variations, and products with paragraph fields.
Incremental product migrations
For ongoing product imports, use the migration framework with Migrate Plus and Migrate Tools to set up incremental migrations that only import new or changed products. The CSV example migrations can be adapted for this purpose.
Tips
- Use drush migrate:import --limit=5 to test migrations with a small number of records before running full imports
- Use drush migrate:import --idlist=42 to import specific records for debugging
- Run migrations in the correct order - stores first, then products, then orders. The migration_dependencies in YAML files define these relationships
- For development, keep rollbacks fast by limiting the number of migrated records. Order rollbacks can be slow due to the extra steps to preserve order items
- The CSV example module migrations are templates - copy them to a custom module and modify for your specific data structure
- When migrating from database sources, use a separate settings.local.php file to define the source database connection
- Check the migration map tables (migrate_map_*) in the database to debug migration issues and see what has been migrated
- For CSV sources, export data with proper quoting (quote all text cells) to avoid parsing issues
- Use scripts/cp_migrations script to copy migration YAML files to config/install for use with Migrate Plus
Technical Details
Troubleshooting 6
Ensure you have created and saved at least one Commerce store before running order migrations. Run the store migration first or manually create a store.
The commerce_migrate.migrate_product event subscriber should automatically preserve variations. If issues persist, ensure the commerce_migrate module is enabled and its event subscribers are registered.
Commerce 1.x stores prices in minor units (e.g., cents). The commerce1_migrate_commerce_price process plugin should convert these automatically. Verify that the fraction_digits property is being set correctly in your source plugin.
The Ubercart migration uses event subscribers to change entity types from 'node' to 'commerce_product'. Ensure the commerce_migrate_ubercart module is enabled and its PrepareRow event subscriber is active.
For CSV migrations, verify that CSV files are placed in the correct directory (usually sites/default/files) and that the path in the migration YAML matches. Check file permissions for web server access.
Review the static_map process plugin configuration in your order migration YAML. Customize the state mappings to match your Commerce 2 workflow (e.g., map 'pending' to 'validation' instead of 'completed' if using validation workflow).
Security Notes 3
- When configuring source database connections, ensure credentials are not committed to version control
- CSV files containing customer data should be protected and removed after migration is complete
- Review migrated data for sensitive information like payment details - the module does not migrate actual payment credentials, only transaction records