Migrate from commercetools to Medusa: what the move involves
Moving from commercetools to Medusa is a data, mapping and integration project, not a file copy. Your catalog, prices, customers and orders have to be exported, reshaped into Medusa's modules for products, pricing, customers and orders, and then checked against the storefront, payment and fulfillment systems that depend on them. Platform teams usually run this work in-house, often with an implementation partner for the export scripts, the data mapping and the cutover plan. Renewal dates, licensing changes, data residency rules and lock-in are the common reasons to start, but the effort is driven by how much custom logic you have built on top of commercetools, not by the number of products. Medusa's core commerce framework is MIT licensed, so the software itself carries no license fee. Some features, including role-based access control in the Enterprise Edition, require a commercial agreement with MedusaJS, Inc., so confirm early which capabilities your admin users, approval flows and staff permissions depend on. Ask the vendor for the written list of Enterprise features that map to your current setup before you commit to a design. Medusa is also available as Medusa Cloud managed hosting, so decide whether your team will run the database, cache and server instances itself or pay someone else to do it.
The most time-consuming part is usually the mapping. Confirm how your commercetools product types, custom fields and channel-specific prices translate into Medusa product, variant, price set and region concepts, and document every field you cannot map one-to-one. Plan the export from the Merchant Center or the HTTP API, check file size limits for each resource, and verify record counts after each import. Plan to run both systems in parallel for a period so you can compare orders, inventory movements and payment events before you switch storefront API calls. Name one owner for each data domain and agree on a rollback point before cutover. Confirm these scope and timing details in writing with your implementation partner before work begins.
Which commercetools capabilities map cleanly to Medusa
This table maps commercetools capabilities to Medusa modules and marks each as clean, needs rework or gap. Use it to scope which data and logic move directly, which need redesign, and which require confirming against current Medusa documentation or the Enterprise Edition before you commit to a plan.
| Capability | Medusa equivalent | Status | Migration note |
|---|---|---|---|
| Product catalog and product types | Product module with product types and options | Needs rework | Product types and attributes must be flattened into Medusa product fields, options and metadata; variant structure needs a mapping review. |
| Categories | Product categories | Clean | Category hierarchy and product assignments can be recreated from a category export; confirm handling of multiple category assignments. |
| Prices and price lists | Pricing module with price sets and regions | Needs rework | Channel and customer-group prices must be remapped to Medusa price sets; confirm each price list rule against current documentation. |
| Customers and addresses | Customer module | Clean | Core profile and address data map directly; password hashes generally cannot be exported, so plan for customer re-authentication. |
| Carts and checkout | Cart module and checkout workflows | Needs rework | Checkout logic built in commercetools extensions must be rewritten as Medusa workflows and API calls in your storefront. |
| Orders and order history | Order module | Needs rework | Historical orders can be imported as records for reference, but order editing and fulfillment states need validation against your flows. |
| Promotions and discounts | Promotion module | Gap | Complex cart predicates and stacking rules may not map one to one; confirm each rule against current Medusa documentation. |
| Inventory and stock locations | Inventory module with stock locations | Clean | Stock levels per location map directly; confirm how multi-warehouse reservations behave in your version. |
| Multi-region and currencies | Region and currency configuration | Needs rework | Regions and tax settings must be rebuilt per market; confirm tax calculation and regional pricing against your legal requirements. |
| Custom fields and Custom Objects | Custom modules, metadata and data models | Gap | Custom Objects have no direct equivalent; they require a custom Medusa module with its own data model and migration scripts. |
| Extensions, webhooks and subscribers | Subscribers, workflows and event bus | Needs rework | Each commercetools extension must be re-implemented; Medusa's Redis-based event bus runs in the worker instance. |
| Role-based access control for admin users | Admin access controls | Gap | Role-based access control features require the Enterprise Edition under a commercial agreement with MedusaJS, Inc.; confirm current scope before relying on it. |
What to export from commercetools and what to rebuild
Each card covers one data group or integration family you will move. Export data in the order the Merchant Center and HTTP API allow, then rebuild the connections that depend on that data. Confirm current formats and limits in your own commercetools project before you schedule the work.
Product and category exports
Merchant Center exports give you product and category data as CSV or JSON, depending on the resource type. Export a sample from each product type so you can see how variants, attributes and localized fields appear before you write any mapping code. Check that category trees and product-to-category assignments are complete, since Medusa's product catalog needs both. Confirm the current export format for each resource in your project.
Customers, prices and orders
These records carry the most business risk, so export them separately and reconcile counts after each run. Export prices per price channel and currency, because Medusa maps them into its pricing module using its own region and currency rules. Customer records can be exported, but confirm with commercetools whether credential data can leave the platform, and plan a password reset flow either way. Keep order history exports for support and accounting, even if only recent orders become live data in Medusa.
HTTP API for remaining data
Anything the Merchant Center does not export needs the HTTP API. Custom Objects, inventory and some order fields may require paginated queries, which you should write and test against a copy of the project first. Store each response as a raw JSON snapshot before transforming it, so a mapping error can be fixed without querying production again. Check the rate limits and authentication scopes in the commercetools documentation before scheduling long extractions.
Re-import file size limits
Files you plan to load into Medusa are subject to size limits on the export side and the ingestion side of the move. Split large product and customer files into batches sized to what your import script can process within its timeout, and record which batch failed when a run stops. Confirm the limits for the exports you take from commercetools and for the import path you build, since a limit on either side changes the batching plan. Run a full-volume test import in staging before the cutover.
Payments, ERP and OMS links
commercetools usually connects to payment providers, ERP and order management systems through its API, subscriptions and webhooks, and each connection must be re-established on the Medusa side. Map each payment provider to a Medusa payment provider module, then test authorization, capture and refund flows with sandbox credentials. Inventory and fulfillment updates need a defined source of truth during cutover, or stock counts in the ERP and OMS will drift. List every subscriber, webhook and scheduled job in your commercetools project before you start.
Storefront calls, search and S3 files
Storefront code calls commercetools endpoints directly, so every request path, authentication flow and cart call changes when you move to the Medusa API. Search indexes and product images also need a new home. Medusa's production setup uses S3 for file storage, so move image files there and rewrite the stored URLs. Keep the commercetools endpoints live until the storefront and search index pass end-to-end tests, and use the Medusa deployment docs to confirm the production file storage setup.
The migration sequence from inventory to decommission
This sequence moves a commercetools store to a self-hosted Medusa backend in controlled stages, so each data set, integration and order flow is verified before the commercetools tenant is switched off. Each step produces a written artifact that the next step depends on.
Inventory data, integrations and extensions
Your team lists every commercetools resource in use: product types, products, categories, prices, customer groups, customers, orders, Custom Objects, discounts, shipping methods and tax settings. Alongside the data, list every API client, webhook subscription, Connect or subscription application, payment connector and extension that reads or writes to the project. The output is an inventory document with one row per resource and integration, an owner for each, and a note on whether it is migrated, rebuilt or retired. Confirm the export options for each resource in the commercetools documentation before you count on them.
Run a pilot store on a subset of products
Choose a small category of products that covers the attribute types you use most, such as simple products, variants with prices in more than one currency, and one bundle or configurable product. Export them from commercetools, load them into a Medusa instance running on a non-production PostgreSQL database and Redis, and render them in a test storefront. The output is a pilot report listing every product that imported, every field that was dropped or transformed, and every storefront page that failed to render. Use this report to decide which mapping rules need revision.
Sign off the mapping document
Product type and attribute definitions, custom fields, price selectors and channel or store scoping are mapped from commercetools concepts to Medusa modules for products, pricing, inventory and regions. Business owners, merchandising and finance review the mapping document line by line, with the pilot report as evidence. Engineering signs off on the data model and the owners of each commercial rule, such as tax and promotions, approve their own rows. The mapping is approved only when every inventory row has a target, and every dropped field has a named owner who has accepted the loss in writing.
Perform the full data load into Medusa
Run the full export in a fixed order: categories and product types first, then products and variants, prices, customers and customer groups, and finally historical orders if you migrate them. Load into a staging Medusa environment that uses the same server and worker layout you plan to run in production, with the predeploy migration step applied before startup. Image files are not carried by CSV-style exports, so plan a separate transfer from the original image URLs into S3-compatible storage. The output is a reconciliation report comparing record counts and sampled values per resource between commercetools and Medusa, with every difference explained.
Rebuild integrations and verify order flows
Replace each commercetools subscription, webhook consumer and API client with Medusa workflows, subscribers or scheduled jobs running in the worker instance, and point the storefront at Medusa's store API. Test cart creation, promotions, tax calculation, payment capture, fulfillment and refunds end to end in staging. Confirm that the /health endpoint reports healthy on both the server and worker before each test run. The output is a signed order-flow test record for each flow in the inventory, with the test data, expected result and actual result attached.
Run both backends in parallel
Keep commercetools live as the system of record while Medusa receives a controlled copy of new catalog changes and a share of test traffic, or while a small set of real orders runs through Medusa under supervision. Compare order totals, tax, stock levels and customer records between the two systems each day. The output is a parallel-run log showing every discrepancy, its root cause and its fix. Agree the exit criteria for this stage with finance and operations in advance, and record the sign-off when they are met.
Cut over the storefront and final sync
Freeze catalog edits in commercetools for a short window, run a final delta export and import into Medusa, switch DNS or the storefront configuration to the Medusa store API, and confirm live order flows against the cutover checklist. Keep the commercetools project read-only and retain its exports for the period your records policy requires. Confirm with your compliance and legal owners what retention applies to customer and order data before deletion.
Decommission commercetools and archive evidence
Once the post-cutover period passes without critical defects, revoke API clients and integration credentials in commercetools, cancel or downgrade the subscription according to your contract terms, and remove the commercetools endpoints from monitoring. Archive the inventory, mapping document, reconciliation reports, order-flow tests and parallel-run log together, because these records are your evidence of completeness if an auditor or customer later asks how data moved. Ask your commercetools account team to confirm in writing what data remains in the project after closure.
How Medusa runs in production during the cutover
A self-hosted Medusa deployment is not one process. It needs a PostgreSQL database, a Redis database, and two Medusa instances: one in server mode, which serves the API and admin dashboard, and one in worker mode, which runs background tasks. During the cutover, both instances must point at the same database and Redis, so plan the infrastructure before you import any data. Decide where each component runs, who owns its backups, and how the two Medusa processes will be scaled and restarted independently.
Production mode also changes which modules are active. The development defaults are replaced with Redis-based caching, an event bus, the workflow engine and locking, and S3 is used for file storage, so product images and other uploads do not sit on the application server. Confirm the bucket, credentials and access policy for S3 (or an S3-compatible store) with your infrastructure team before the first import, because migrated product images depend on it. Confirm the exact configuration keys in the Medusa deployment documentation for your release, since the names and defaults can change between versions.
Two settings need explicit ownership. COOKIE_SECRET and JWT_SECRET must be set separately for the server and the worker, stored in your secrets manager, and rotated under a documented procedure. Run database migrations through the predeploy script before each startup, and make sure a failed migration blocks the rollout rather than leaving the API on an old schema. After each deployment, check the /health endpoint on both instances before you move traffic. If your organization wants a managed option instead, Medusa Cloud is offered as hosted alternative to self-hosting, but confirm its hosting regions, support terms and data location in writing before you choose it.
How the migration changes by store size and starting point
A single-region store with a modest product catalog usually has the shortest path. The data set is small enough to export through the Merchant Center and re-import with a scripted pass, and most of the effort falls on the storefront. Medusa's core product, pricing and cart modules cover the typical shape of this catalog, so the main question is how many custom product attributes need a home in the new data model.
- Export scope: Products, categories, customers and orders, with a short list of attributes to map.
- Pricing: One currency and one price list, which keeps the price mapping direct.
- Storefront: Switch API calls from the commercetools endpoints to Medusa's Store API in one pass.
- Sequence: Load a staging instance, run test orders end to end, then cut over during a quiet period.
- Parallel running: Keep commercetools live for orders until a full order cycle has been verified in Medusa.
Before you start, confirm the export file size limits for each resource type and check the record counts against your staging import.
A store that sells in several regions or currencies carries the most mapping work. Prices, tax rules, shipping options and stock locations all vary by market, and each one has to be mapped to a Medusa region or price list with the same effect the commercetools configuration has today. Exports tend to be larger, so plan the import in batches and verify totals per market rather than only in aggregate.
- Regions: Define each market, its currency and its tax behavior before importing prices.
- Price lists: Confirm how commercetools price scopes map to Medusa price sets, including any customer group pricing.
- Inventory: Map stock per location and check that availability is calculated the same way in each market.
- Localization: Move translated product content and confirm how the storefront selects locale.
- Verification: Compare sample prices in every market against the live commercetools store before cutover.
Ask your implementation partner to document the price and tax rules per market in writing, since errors in this layer are visible to customers immediately.
B2B stores depend on company accounts, buyer roles, approval flows and negotiated prices. Medusa supports B2B use cases through its modules, but some controls that teams rely on may sit in the Enterprise Edition, which requires a commercial agreement with MedusaJS, Inc. The migration therefore starts with an inventory of which account rules are business-critical, followed by a decision on whether each one is built, bought or simplified.
- Account data: Export customers and map company hierarchies, contacts and addresses to Medusa customer and group structures.
- Negotiated pricing: Recreate customer-specific prices and confirm how they are applied at checkout.
- Roles and approvals: Check whether role-based access control is needed and whether it falls under the Enterprise Edition.
- Quotes and orders: Document any quote or purchase order flow that commercetools handles today and plan its rebuild.
- Access: Confirm that buyer logins, password policies and single sign-on requirements carry over.
Confirm with MedusaJS, Inc. which of your required B2B features are covered by the open-source core and which need a commercial agreement before you fix the scope.
Stores with many custom extensions, such as bespoke pricing engines, ERP connectors, fulfillment logic or custom checkout steps, face the largest rebuild. Each commercetools extension, subscription or API client has to be inventoried, classified and either moved into a Medusa module, workflow or subscriber, or retired. The sequence matters because downstream systems often depend on the order of events and the timing of webhooks.
- Inventory: List every extension, subscription, scheduled job and integration that reads or writes commercetools data.
- Classification: Mark each one as rebuild, replace with a managed service, or remove.
- Event flows: Map which events trigger which downstream calls and test them against Medusa's event handling.
- Background work: Plan which tasks move to the Medusa worker instance and confirm they run reliably there.
- Staged cutover: Migrate integrations one domain at a time, starting with the lowest-risk ones.
Ask for a written integration map from your implementation partner before estimating effort, because the number of extensions determines the schedule more than the size of the catalog.
What drives migration cost and duration
Migration cost and duration rise with how much commercetools configuration you must reproduce by hand, not with the number of products you sell. The cards below cover the decisions that move the estimate most, plus the recurring and one-time cost lines a written quote should separate.
Product types and custom fields
Every commercetools product type, attribute and custom field must map to a Medusa product model, custom module or metadata field before any data moves. Count them early, because each unmapped attribute adds a mapping decision and a validation pass on the imported catalog. Ask the vendor to list product types, attribute definitions and custom types in a single inventory, and flag any field that drives pricing, availability or search, since those need the most testing.
Extensions and API connectors
commercetools extensions and API Extensions run synchronous logic on cart and order calls, and each one must be rebuilt as Medusa workflow steps, subscribers or custom API routes. The work scales with the number of extensions and the complexity of their business rules, not with their line count. Ask for a list of every extension with its trigger point and the data it reads and writes, so the quote can price each rebuild separately.
Integrations to rebuild
ERP, tax, payment, shipping, search, marketing and warehouse connections usually depend on commercetools webhooks, subscriptions or specific API payloads. Each integration needs its message formats remapped, its credentials moved into the new environment and its failure handling retested. Inventory every system that receives commercetools events, and record which ones are owned by a third party, because those owners may need to approve the change.
Order history volume
Historical orders carry payment references, returns, tax lines and customer links, and importing them is slower and more error-prone than importing products. A large history increases the validation and reconciliation work, and it may not justify a full import if reporting can read from an archive instead. Decide which order fields must be queryable in Medusa and which can stay in an archive export, and ask the quote to state which option it assumes.
Data quality and cleanup
Duplicate SKUs, missing prices by currency or channel, inconsistent category trees and broken image references cost more to fix after import than before. Medusa's model expects clean price sets and variant options, so messy source data becomes a rework item during testing. Run a data audit on the commercetools export before estimating the import, and ask the vendor to name which cleanup tasks are in scope and which stay with your merchandising team.
Parallel run and internal capacity
Running commercetools and Medusa side by side until order flows are verified adds recurring subscription cost for the overlap period, plus staff time for reconciliation. Your internal engineers, who must review mappings, approve cutover steps and own the new platform, are often the real constraint. Ask the quote to state the parallel run length it assumes, who performs reconciliation and which internal roles are needed each week.
One-time and recurring costs
One-time costs cover discovery, data mapping, extension and integration rebuilds, storefront API changes, testing and cutover. Recurring costs cover the Medusa hosting components: the server and worker instances, PostgreSQL, Redis, S3-compatible file storage, monitoring, backups and upgrades, plus the engineers who operate them. Medusa's core is MIT licensed, but Enterprise Edition features need a commercial agreement with MedusaJS, Inc., so ask whether any required feature falls in that group.
How long does a commercetools to Medusa migration take and who does it?
How long does a commercetools to Medusa migration usually take?
No duration is published for this migration, and the honest answer depends on the scope. The main drivers are how many product types, custom fields, price lists, channels and extensions you run, how many orders and customers you must carry over, and how much checkout logic you rebuild. A catalog with a few product types and no custom extensions is a very different project from a multi-market store with bespoke promotions and several ERP or fulfillment integrations. Ask for a timeline in the written scope, which lists the phases, deliverables and the points where you verify data before cutover.
What does a commercetools to Medusa migration cost, and what are the cost components?
Cost falls into a few components: the engineering effort to map data and rebuild extensions, the infrastructure you run (PostgreSQL, Redis, S3-compatible file storage, and two Medusa instances, one in server mode and one in worker mode), the storefront work to switch API calls, and the testing and cutover effort. Infrastructure and maintenance recur every month, while mapping, rebuilding and cutover are largely one-time. Costs rise with custom fields, bespoke pricing logic and integrations. Ask any vendor, including DeployOpen, for a quote built from a written scope rather than a flat figure.
Can our internal team migrate from commercetools to Medusa by itself?
A team with strong Node.js and TypeScript skills and experience with PostgreSQL can carry out the work, provided someone owns the data mapping and the cutover plan. The steps that most often stall internal teams are reconciling exported data against the HTTP API, rebuilding discounts and tax logic, and proving that orders, payments and fulfillment flows behave the same after switching. Decide early whether you need the Enterprise Edition features and whether those are covered by a commercial agreement with MedusaJS, Inc.
What must our internal team provide before the migration starts?
Your team should provide access to the commercetools project and API credentials, a complete inventory of product types, custom fields, categories, price lists and channels, and a list of every integration that reads or writes commerce data. You also need named owners for the storefront, payments, tax, ERP and fulfillment systems, and a decision on the production hosting account where Medusa will run. Without these, any estimate is guesswork, so ask the provider to list them as prerequisites in the written scope.
What makes a commercetools to Medusa migration risky?
The main risks are incomplete exports, lost custom fields, and order history that cannot be matched to customers after the move. Run both backends in parallel until order flows are verified, and keep the commercetools project available for reconciliation during that window. Confirm how your payment provider and tax service will be reconnected, because those integrations often carry more risk than the catalog itself.
When is it worth bringing in an implementation partner?
A partner is worth considering when the catalog or order history is large, when several integrations must be rebuilt, when you have regulatory or residency obligations that shape hosting, or when your team lacks capacity to run a parallel cutover. DeployOpen plans, implements, hardens, backs up and documents self-hosted platforms in your own infrastructure, and most engagements are fixed-scope with deliverables and timelines agreed in writing before work starts. Ongoing support and upgrades are available as retainers.
What should a written scope for this migration include?
A useful scope lists the data domains in scope (products, categories, customers, prices, orders), the exact export method for each, the mapping document, the extensions to rebuild, the storefront changes, the hosting and backup design, the verification steps and the cutover plan. It should also name what is out of scope, such as data you will archive instead of migrate, and state who signs off each phase. Ask for the acceptance criteria in writing so both sides know when the migration is complete.
How DeployOpen scopes and runs the migration
DeployOpen plans and implements self-hosted Medusa inside your own cloud accounts or data centers, and migrates commercetools data and integrations into that environment. Engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work starts.
How we scope
- Written scope lists which commercetools resources move: products, categories, customers, prices and orders.
- Scope records the product types, custom fields and extensions that need a Medusa module mapping.
- Scope names the storefront API calls to switch and the integrations to rebuild or retire.
How we build
- Deploy Medusa server and worker instances with PostgreSQL and Redis in your infrastructure.
- Map product types and custom fields to Medusa modules, then run test imports against a staging copy.
- Rebuild extensions and integrations, and test orders, carts and pricing before any cutover.
How we hand over
- Deliver documentation for the deployment, data mapping, migration runbooks and rollback steps.
- Hand over configuration for secrets, database credentials, file storage and health checks.
- Walk your engineers through the parallel-run results and the signed-off checklist before cutover.
How we support
- Ongoing support, upgrades and continuous testing are available as a retainer after handover.
- Retainer scope covers Medusa version upgrades, backups and monitoring of the self-hosted stack.
- Confirm response expectations and upgrade cadence in writing when agreeing the retainer.
