DocumentationCommerceAdobe Commerce as a Cloud Service

[SaaS only]{class="badge positive" title="Applies to Adobe Commerce as a Cloud Service and Adobe Commerce Optimizer projects only (Adobe-managed SaaS infrastructure)."}

Bulk data migration tool

Last update: July 28, 2026

CREATED FOR:

  • Intermediate
  • Developer
IMPORTANT
The bulk data migration tool is currently in Early Access. Access is provided exclusively through the Commerce Deployed Engineering (CDE) engagement process.

The bulk data migration tool enables system integrators to migrate first-party core commerce data from Adobe Commerce on Cloud or on-premises installations to Adobe Commerce as a Cloud Service.

The bulk data migration tool is a Docker-based CLI that system integrators run on their own migration machine. It connects to the source instance, extracts first-party core commerce data, uploads it to Adobe’s migration service (Commerce Data Migration Service), and monitors progress through to completion.

All commands are run locally, so you control when the migration starts, when maintenance mode is applied, and when each phase runs.

Migration workflow

The tool manages the following stages end-to-end:

  • Data extraction — extracts first-party core commerce data from the source instance (Adobe Commerce on Cloud or on-premises).
  • Data loading — loads extracted data into the target Adobe Commerce as a Cloud Service instance.
  • Data integrity verification — performs automated post-migration checks including REST and GraphQL API comparison and record count validation.
NOTE
Currently, the bulk data migration tool supports migrating first-party core commerce data only. Custom data migration is not currently supported. Configuration settings (store settings, system configuration) are not migrated automatically and must be set up on the target instance independently prior to migration.

Architecture

The bulk data migration tool follows a distributed architecture that enables secure and efficient data migration. This tool helps system integrators migrate data from an existing Adobe Commerce on Cloud or on-premises instance to Adobe Commerce as a Cloud Service. For more information on the migration process, see the Migration overview.

The following image details the architecture and end-to-end data flow using the bulk data migration tool.

Bulk data migration tool architecture diagram showing PaaS to SaaS data flow {modal="regular"}

Components

Component
Role
Bulk data migration tool
The Docker-based CLI that the system integrator runs on the migration machine, which orchestrates the full pipeline by reading the schema and data from the source, uploading extracted data to Adobe’s migration service, and driving status transitions.
Source instance (Commerce on Cloud or on-premises)
The migration source. The tool connects through REST and GraphQL APIs and through an SSH tunnel (Adobe Commerce on Cloud) or through a direct database connection (on-premises) for data extraction.
Commerce Data Migration Service (CDMS) API
Adobe-managed REST API that registers migrations, coordinates state transitions, and provides secure endpoints for uploading extracted data. The migration tool connects to this API using the CDMS endpoint URL and IMS credentials in your .env configuration.
Commerce Data Migration Service (CDMS) worker
Adobe-managed background service that loads extracted data into the target instance and runs post-load integrity verification.
Adobe Commerce as a Cloud Service
The SaaS-based version of Adobe Commerce and your migration target. Receives loaded data and exposes Catalog, Live Search, and pricing rule services used during integrity verification.

Data flow

Data moves through the components in the following sequence:

  1. The bulk data migration tool reads the database schema and data from the source instance, through an SSH tunnel for Adobe Commerce on Cloud or a direct database connection for on-premises.

  2. The tool registers the migration and uploads the extracted data through the CDMS API.

  3. The CDMS worker loads the data into the target Adobe Commerce as a Cloud Service tenant.

  4. Adobe Commerce as a Cloud Service ingests the loaded catalog data and builds the catalog index.

  5. The Commerce Data Migration Service (CDMS) worker verifies the loaded data through database checksum comparison, REST, and GraphQL across the following services:

    • Catalog (GraphQL) — product and category data.
    • Live Search (REST) — search index correctness.
    • Pricing rules (REST) — price and rule data.

  6. The tool polls the migration status throughout and retrieves the final migration report on completion.

Engagement lifecycle

Access to the bulk data migration tool is provided exclusively through a Commerce Deployed Engineering (CDE) engagement. The tool is not publicly accessible.

The typical engagement lifecycle is:

  1. CDE Discovery - Complete the initial scoping call, assess data footprint and complexity, and complete the scoping questionnaire.
  2. Deal Sign - The commercial agreement is in place and the migration scope is confirmed. At this stage, you are granted access to the migration tool.
  3. CDE Co-Innovation and Support - Work jointly with Adobe to install the tool in your environment and execute test migrations.
  4. Go Live - Run the production cutover migration and complete data integrity verification.

Tool distribution

The tool is distributed as part of the CDE engagement. Your Adobe representative provides the tool package, which includes:

  • The Docker-based CLI and build configuration
  • An .example.env configuration template with documentation for all required environment variables
  • Comprehensive technical documentation covering the tool’s architecture, configuration reference, custom transformation and test frameworks, and troubleshooting guides

For detailed setup and operational instructions, refer to the documentation included in the tool distribution package.

Migration guides

The following pages demonstrate the full migration lifecycle, from preparation to execution. For a complete understanding of the migration process, review them in the following order:

  1. Customer readiness checklist — Confirm the engagement, migration machine, source, and target prerequisites before you request tool access.
  2. Verify migration service access — After obtaining access to the tool, validate network reachability, IMS authentication, and tenant authorization against the Commerce Data Migration Service (CDMS) API.
  3. Run a bulk data migration — Configure the tool, prepare your network and instances, and begin the migration.

For the full configuration reference, custom transformation and test frameworks, and troubleshooting guidance, refer to the documentation included in the tool distribution package.

recommendation-more-help
commerce-help-cloud-service