Migrate from Salesforce Commerce Cloud to Medusa

Migrate from Salesforce Commerce Cloud to Medusa: what the move involves

For an enterprise B2C team, moving from Salesforce Commerce Cloud to Medusa is a re-platforming of catalog, pricing, promotions, checkout and integrations, not a copy of data from one store into another. The XML exports can carry products, customers and orders out of Business Manager, but every commerce rule behind them has to be rebuilt in Medusa's modules for carts, orders, product catalogs, pricing and inventory. Most teams doing this have an internal platform team that owns the new stack, with an implementation partner covering the storefront, integrations and cutover. Effort and risk are driven less by the volume of records than by how many cartridge behaviors, price book rules and tax or promotion logic your current store depends on. Confirm that inventory early, because it sets the size of the rebuild.

Medusa is open core. The core commerce framework is MIT licensed, so the code you run can be used without a license fee. Enterprise Edition features based on role-based access control require a commercial agreement with MedusaJS, Inc. If your merchandising, support or back-office teams need granular roles and permissions in the admin, ask the vendor in writing which of those features are in Enterprise Edition and what the agreement covers, before you design around them. Also ask whether the managed option, Medusa Cloud, is part of the decision or whether you are only evaluating self-hosting. Treat the answers as inputs to the cost comparison, not as details to settle later.

Self-hosting changes who carries the operational load. Medusa needs a PostgreSQL database and a Redis database, plus two Medusa instances: one in server mode for the API and admin dashboard, and one in worker mode for background tasks. Production also replaces development modules with Redis-based caching, the event bus, the workflow engine and locking, and uses S3 for file storage. Each deployment runs database migrations through a predeploy script before startup, so plan migration rollbacks as part of cutover. Your platform team will own secrets such as the cookie and JWT values for both instances, health checks against the /health endpoint, backups and upgrades. Ask your implementation partner to show how each of these is handled in your own cloud account before the work is scoped.

Which Commerce Cloud capabilities map cleanly to Medusa

This table compares common Salesforce B2C Commerce capabilities with what Medusa provides out of the box, using its documented modules for carts, orders, product catalogs, pricing and inventory. Read each row as a starting estimate: clean means a documented Medusa module covers the need, needs rework means the logic must be rebuilt on Medusa's extension points, and gap means you should plan and confirm a custom or third-party solution before committing.

Capability	Medusa fit	What to confirm or rebuild
Product catalog	Clean	Map XML product and variant exports to Medusa product and variant records, and confirm how your attribute sets and custom fields are modeled
Pricing and price books	Needs rework	Price books must be remodeled as Medusa pricing sets and price lists; confirm currency, region and tier handling against current docs
Inventory and stock	Clean	Inventory is handled by a dedicated module; confirm multi-location stock behavior matches your fulfillment setup
Carts	Clean	Cart module covers line items and totals; confirm how any custom cart logic from SFCC pipelines is re-expressed as workflow steps
Orders and order history	Needs rework	Historical orders can be imported, but statuses, payment records and returns need mapping and testing
Customers and addresses	Needs rework	Customer records and addresses map to Medusa customer modules; password hashes and login sessions usually cannot be migrated and need a reset path
Promotions and coupons	Needs rework	Rebuild promotion rules and coupon codes in Medusa's promotion module; confirm each SFCC discount type has an equivalent
Checkout flow	Needs rework	Checkout is assembled in your storefront against Medusa APIs; plan payment provider and shipping integrations explicitly
Storefront rendering	Gap	SFRA or PWA Kit templates and cartridge rendering logic do not carry over; the storefront is a new build
Site-level features and personalization	Gap	Confirm whether site preferences, content slots, personalization and search features have Medusa equivalents or need separate services
B2B and marketplace needs	Clean	Medusa documents B2B and marketplace use cases; confirm specific B2B features such as approvals and quotes against current docs

Which exports and integrations move, and which must be rebuilt

Most of the data leaving Salesforce Commerce Cloud travels through a few documented export paths, but each one lands in a different shape than Medusa's data model expects. The cards below separate what can be carried across as data from what has to be rebuilt as Medusa modules, subscribers and workflows, and where each item needs checking in your own instance.

Business Manager XML exports

XML exports from Business Manager are the main path for catalog, price book and customer data. Map each XML element to Medusa's product, variant, price and customer records in a staging script, not by hand. Exports depend on the schema version and the site configuration in your own instance, so run a sample export and confirm every field you rely on before writing the mapping. Plan for multiple price books to become Medusa price lists or regions, which needs a decision on currency and tax handling per market.

Coupon codes as CSV

Coupon codes export as CSV and are the input for rebuilding discounts. Medusa expresses promotions through its promotion module, so each code needs a mapping to a promotion type, a validity window, usage limits and any product or customer scope. Codes that carry per-customer or single-use restrictions need explicit rules, because a plain CSV import does not preserve the logic behind them. Confirm the column layout in your own export before building the import.

Customer and order history

Customer profiles and order history move as data, but orders are the riskiest path. Medusa's order module needs consistent line items, statuses and payment records, so historical orders are usually imported as read-only archive records rather than as live orders. Decide which customer fields become Medusa customers, which stay in an archive store, and how password hashes are handled, since they generally cannot be carried across. Confirm the export scope in your own instance.

Site and configuration exports

Site exports carry storefront configuration such as locales, currencies, shipping and tax settings. These do not map one to one onto Medusa, so treat them as a specification to read, not as an import file. Use the site export to document what each market needs, then configure Medusa regions, tax providers and fulfillment options against that list. Any setting you cannot trace to a Medusa module should be logged as an open decision for the team.

CRM and marketing integrations

Connections to CRM and marketing tools in the Commerce Cloud estate usually run through cartridges or external services. In Medusa these become subscribers that react to events such as order placed or customer created, and workflows for multi-step tasks. Each integration needs an inventory of the events it consumes, the fields it writes back, and whether it runs synchronously. Build the event contract first so the CRM team and the commerce team agree on payloads before code is written.

Payment, tax and order management

Payment, tax and order management connectors need Medusa payment, tax and fulfillment providers or custom modules. Payment providers handle authorization and capture, tax providers calculate rates per region, and fulfillment providers connect to warehouses or an external order management system. Each connector must be rebuilt against the new provider's API and tested end to end in a sandbox. Confirm with your payment processor and tax engine that their tokens, refunds and reporting can be reproduced in the new stack.

The migration sequence from inventory to decommission

This sequence moves a Salesforce Commerce Cloud estate to a self-hosted Medusa stack in controlled stages, so each site, catalog and order flow is proven in a non-production environment before any customer traffic moves. Each step ends with a named artifact that the next step depends on.

Inventory sites, cartridges, price books and integrations
Your team and the migration partner list every storefront site, each cartridge and its custom logic, every price book and promotion, and each integration with payment, tax, ERP, OMS, CRM and shipping systems. Business Manager configuration, site preferences and custom attributes are recorded alongside them. The output is an inventory workbook with one row per capability, an owner and a disposition: rebuild in Medusa, replace with a third-party service, or retire. The step is done when the business owners have signed off every row, including the features nobody has used in a long time.
Map XML exports to the Medusa data model
Using the XML exports from Business Manager, engineers map catalog, category, price book, customer and order fields to Medusa's product, variant, price set, customer and order modules. Mapping decisions cover SFCC site and locale concepts that become regions, sales channels and currencies in Medusa, along with the handling of custom attributes. The output is a field-level mapping document and the import scripts that read the XML and write through Medusa's APIs or seed workflows. The step is done when a sample export loads into a local Medusa instance and the record counts match the source.
Pilot a catalog and checkout in non-production
The team stands up a non-production Medusa environment with PostgreSQL, Redis, S3 for file storage and two Medusa instances, one in server mode and one in worker mode. A subset of the catalog, one region and one payment provider are loaded, and the storefront checkout is rebuilt against Medusa's store APIs. Promotions and tax rules are rebuilt and tested against the inventory list. The output is a working pilot, a checkout test log and a list of gaps that need a decision. The step is done when the pilot passes the agreed test scripts and the deployment responds on its /health endpoint.
Run a parallel period with test orders
Both Commerce Cloud and Medusa take the same set of test orders, including returns, partial refunds, promotions and cross-region carts. Order data is pushed to the downstream ERP, OMS and warehouse systems from both stacks so teams can compare what each system records. Monitoring covers the Medusa server, the worker queue and the database. The output is a reconciliation report that lists every order, payment, tax and stock difference with its root cause and fix. The step is done when the open differences are zero or accepted in writing by the business owner.
Cut over with a data freeze and routing switch
The team announces a freeze window, stops catalog and price changes in Commerce Cloud, and runs a final delta export of customers, orders and open carts. The delta is imported into the production Medusa database, and the run is checked against the reconciliation report. Then DNS or the edge routing layer switches traffic to the new storefront, with the rollback path tested beforehand. The output is a cutover runbook with named owners, go and no-go checks, and the rollback steps. The step is done when production traffic is served by Medusa and the post-cutover checks pass.
Verify order history and reporting before decommission
Finance, customer service and analytics teams confirm that historical orders, returns, customer records and reports are available in the new environment or in an archive they can query. Reports are rebuilt from the Medusa data and compared with figures from Commerce Cloud for an agreed period. Retention obligations for order and customer data are confirmed with legal and compliance owners. The output is a signed verification record and an archive of the Commerce Cloud data in a format the business can read. The step is done when every report owner has signed off.
Decommission Commerce Cloud on a confirmed date
Once verification is signed off, the team confirms the contract end date and the data return or deletion terms with Salesforce, and removes integrations, API clients and scheduled jobs that still point at Commerce Cloud. Access is revoked and credentials are rotated. The output is a decommission checklist, a record of data disposition and an updated architecture diagram. The step is done when no production process calls Commerce Cloud and the contract obligations are closed in writing.

What drives the cost and duration of the move

This table lists the factors that most change the effort and budget of moving from Salesforce B2C Commerce to a self-hosted Medusa stack, with the reason each one matters and how to reduce it. Read the driver rows first to scope discovery, then the cost rows to see which charges are one-time and which recur after launch.

Driver or cost	Why it changes effort or cost	How to keep it down
Number of sites and locales	Each site, locale and currency adds catalog mapping, content translation, tax and shipping configuration, and storefront testing. Medusa models regions and currencies, so every market must be defined explicitly.	Confirm which sites are live revenue channels and retire inactive ones before export. Launch the core market first and add locales in later phases.
Price book complexity	SFCC price books, currency rules and customer-group pricing must be translated into Medusa price lists and pricing rules. Dense or overlapping books increase mapping and reconciliation work.	Audit price books for duplicates and stale entries. Agree a target pricing model in discovery so mapping rules are written once.
Custom cartridge logic	Business logic in cartridges (tax, shipping, payment, custom attributes) has no direct equivalent. Each piece is rebuilt as a Medusa module, workflow or API route, and each rebuild needs tests.	Inventory every cartridge hook and classify it as keep, replace with a Medusa feature, or drop. Remove unused code before rewriting.
Promotion rules	Coupon codes, stacking rules, customer-group discounts and campaign schedules must be recreated and tested against orders. Edge cases often surface late.	Export coupon codes and active promotions, then cut scope to rules still used. Build a test matrix from real order history.
Integrations	ERP, OMS, CRM, payment, tax, search and marketing connections each need a new endpoint, webhook or subscriber on Medusa, plus credential handling and monitoring.	List every system that reads or writes orders and customers. Phase integrations behind the core checkout and prioritize those that touch revenue.
Storefront rewrite scope	If the storefront is built on SFRA or PWA Kit, the templates and data calls must be rewritten against Medusa's APIs. Scope grows with custom pages, personalization and checkout steps.	Reuse components and design tokens where possible. Freeze new storefront features during the rewrite window.
Data quality	Duplicate SKUs, incomplete customer records, missing product images and inconsistent attributes slow import and validation. Poor data often causes more rework than code.	Profile exports before build starts. Agree cleansing rules with merchandising and customer service owners.
Hosting model and in-house skills	Running Medusa server and worker, PostgreSQL, Redis, S3 storage and a monitoring stack adds ongoing operations. Staffing gaps are often the largest recurring line.	Decide early whether your platform team will operate the stack or whether a retainer covers upgrades and on-call. Ask for infrastructure sizing in the written scope.
One-time: discovery, build, migration and testing	Discovery, data mapping, rebuilt logic, order and customer migration, parallel run and load testing are paid as project work. Fixed-scope agreements price these from the written scope.	Request a quote that itemizes each phase, the assumptions behind it and the exit criteria for each phase.
Recurring: PostgreSQL, Redis and S3 hosting	Database, cache, event and locking services and object storage are billed by your cloud provider or data center and scale with traffic, catalog size and retention.	Ask your provider for current pricing. Right-size instances after load testing and set retention rules for media and logs.
Recurring: Medusa Cloud or Enterprise agreement	Medusa Cloud is a managed hosting option. Enterprise Edition features based on role-based access control need a commercial agreement with MedusaJS, Inc. The core framework is MIT licensed.	Confirm with MedusaJS, Inc. which features your admin and staff roles require before you assume an Enterprise agreement is needed.

How the move differs by team size and starting point

A single-brand team with a standard storefront usually has the simplest path. The catalog, customer and order exports from Business Manager map to a fairly small set of Medusa modules, and the storefront is the largest new build. Most of the cost sits in the storefront, the checkout flow and the integrations, not in the data.

Catalog and customers: Product, variant, price and customer records convert into Medusa's product and customer modules with a single mapping pass, provided the attribute set is small.
Promotions: Standard coupons and basic promotions are rebuilt as Medusa promotions. Confirm which discount rules are actually in use before counting them.
Checkout: A standard SFRA-style checkout is rebuilt once in a new storefront, so the platform work is mostly configuration of payment, shipping and tax providers.
Platform team: A small team can run the Medusa server, the worker, PostgreSQL and Redis, but someone must own upgrades and on-call duties.
Confirm before scoping: Which storefront is in production today, how many locales and currencies are live, and whether order history must be imported or only referenced.

Ask your implementation partner to list every export file and every checkout step in writing before agreeing a fixed scope.

What usually goes wrong and how to prevent it

Most failed moves off Salesforce Commerce Cloud come from data that arrived incomplete, pricing and promotions that behave differently, or a production setup that was never fully defined. The six cards below cover the points where these problems usually surface, each with a check to run before cutover.

Incomplete export mapping

XML exports from Business Manager use Salesforce's schemas, and fields such as variation attributes, custom attributes and locale-specific values do not map one to one onto Medusa's product, variant and price models. Build a field-by-field mapping sheet and run a reconciliation report that compares record counts and sample SKUs between the source export and the Medusa database. Treat any unmapped field as a blocking defect until someone signs off on it.

Price book and promotion mismatch

Salesforce price books, promotions and coupon codes are scoped differently from Medusa's pricing and promotion modules, so a discount that applied per site or per customer group can silently apply globally or not at all. Rebuild each price list and promotion from a written rule set, then run a staging order for each region and customer group and compare totals against the live Salesforce results.

Checkout and tax errors

Checkout logic in SFRA or PWA Kit, including tax calculation, shipping rules and payment hooks, has to be rebuilt against Medusa's cart and order workflows. Errors often appear only at the edges, such as rounding on multi-currency carts or tax on discounted shipping. Test a fixed set of carts across every shipping address, currency and payment method in a staging environment, and document the expected totals for each one.

Missing worker process in production

A self-hosted Medusa deployment needs two Medusa instances: one in server mode for the API and admin dashboard, and one in worker mode for background tasks. Teams that deploy only the server see orders, emails and scheduled jobs stop without an obvious error. Confirm both processes are defined in your orchestration config, that the worker is running in the target environment, and that its logs are monitored alongside the server.

Secrets and secret handling

The server and worker each require database credentials along with COOKIE_SECRET and JWT_SECRET values. Reusing development secrets, committing them to a repository or setting different values on server and worker will break sessions or authentication in ways that are hard to trace. Store every secret in your vault, rotate them through a documented procedure, and verify the /health endpoint on both processes after each change.

Lost order history and SEO redirects

Historical orders, customer accounts and indexed Salesforce URLs are easy to drop during cutover, which damages customer service records and organic search traffic. Export order history into a read-only archive that your service desk can search, and build a URL map from every indexed Salesforce storefront path to its Medusa equivalent. Keep the old site live until redirects have been verified and write down the rollback steps before the switch.

Questions teams ask before moving from Commerce Cloud to Medusa

What does a move from Commerce Cloud to Medusa cost, and what drives it?

The cost is the sum of several components, and no single license fee dominates. Medusa's core is MIT licensed, so the software itself carries no license charge for the core framework. The recurring costs are the infrastructure you run: a PostgreSQL database, a Redis database, and two Medusa instances, one in server mode and one in worker mode. Build costs cover the storefront, the data conversion from XML exports, the rebuilt promotions and checkout, and integrations with your ERP, payment and order systems. These are largely one-time, though maintenance recurs. Costs rise with the number of sites, locales, price books, custom cartridge logic and third-party integrations. Ask any quote to split one-time work from recurring hosting, support and upgrades, and to name who is paid for each item.

How long does a Commerce Cloud to Medusa migration take?

Duration depends on scope, and no fixed timeline applies to every store. The main variables are the number of sites and catalogs, how much cartridge logic must be rebuilt as Medusa modules or storefront code, how many systems must be reconnected, and how clean the existing data is. Promotions and checkout rules usually take the longest to verify because they affect revenue directly. A fixed-scope engagement sets scope, deliverables and timelines in writing before work starts, which is the right point to compare estimates. Ask for a phased plan that separates data extraction, staging, parallel running and cutover.

Can our internal engineering team migrate to Medusa without outside help?

A capable team can do it alone if it already operates Node.js and TypeScript services, PostgreSQL and Redis, and has someone who owns the storefront build. Medusa is a framework, so the team takes on work that a SaaS platform normally handles: hosting, upgrades, database migrations, caching, the event bus and file storage on S3. The deployment process runs database migrations through a predeploy script before each startup, which your team must operate correctly. Be honest about capacity during the cutover window, since that is when the least spare time exists. Ask whether you need a partner for the hardest parts, such as data mapping, security testing or the parallel run, and whether support is needed after launch.

What does the migration need from catalog, finance and operations teams?

The migration needs decisions from business owners, not only engineers. Catalog owners must confirm which products, variants, categories and attributes are live, and which are retired, before XML exports are mapped to Medusa's product model. Finance must confirm price books, currencies, tax rules and promotion logic, because these determine how pricing and discounts are rebuilt in the pricing module. Operations must define order statuses, fulfillment steps, returns and the integrations that depend on them, including customer service tools. Assign one named owner per area and agree on sign-off criteria in advance, because unresolved decisions are the most common reason for scope to grow mid-project.

Is Medusa free to run, and what does the license cover?

The core commerce framework is free to use under the MIT license, so running the core does not require a license fee. Medusa is open core, however. Enterprise Edition features based on role-based access control require a commercial agreement with MedusaJS, Inc. If your admin access model depends on those features, that agreement becomes a recurring cost to include in the comparison. Medusa is also available as Medusa Cloud managed hosting, which is a separate cost decision from self-hosting. Confirm with MedusaJS, Inc. which features your team requires and whether they sit in the Enterprise Edition before you commit to a design.

How do we run Commerce Cloud and Medusa in parallel during cutover?

Running both platforms in parallel reduces cutover risk, but it adds cost and coordination. Keep Commerce Cloud live until the Medusa catalog, customers, promotions and checkout have been verified against real data. Synchronize or freeze the changes that must flow into the new store, such as product updates, stock levels and orders, and decide which system is the source of truth for each record during the overlap. On the Medusa side, verify the deployment through the /health endpoint on the server and worker instances, and test the predeploy migration path before cutover. Agree a rollback plan with a named owner, and document how orders placed during the overlap will be reconciled.

What security settings must a self-hosted Medusa deployment get right?

Security starts with secrets and access. Each self-hosted Medusa server and worker needs database credentials plus COOKIE_SECRET and JWT_SECRET values, so these must be generated uniquely, stored in a secrets manager and rotated under a documented process. Restrict network access so the PostgreSQL and Redis databases are reachable only from the Medusa instances. Store file uploads in S3 with access policies that match your data classification. Before go-live, test the storefront, APIs and admin dashboard for common application and API weaknesses. DeployOpen can plan and run these security tests, but it does not issue audit reports or certifications. Ask your compliance assessor which controls they need evidence for.

How DeployOpen scopes, runs and supports the migration

DeployOpen plans and implements self-hosted Medusa inside your own cloud accounts or data centers, covering the XML export mapping, promotions, checkout and the server and worker deployment. Engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work starts.

How we scope

Written scope lists which XML exports, coupon files and customer records move into Medusa's data model.
Scope names the promotions, checkout flows and payment integrations to rebuild, with each item marked in or out.
Scope states the PostgreSQL, Redis and S3 components and the two Medusa instances your environment will run.

How we build

We map Salesforce XML catalog and price book fields to Medusa products, variants, prices and inventory modules.
We configure the server and worker instances, production Redis caching, event bus and S3 file storage in your accounts.
We test migration scripts on copies of your exports and check each deployment through the /health endpoint before cutover.

How we hand over

You receive runbooks covering the predeploy migration step, secret rotation for COOKIE_SECRET and JWT_SECRET, and restore procedures.
Documentation records the export-to-import mapping, rebuilt promotion logic and integration contracts for your engineering team.
Handover includes a walkthrough of the server and worker split so your staff can operate and troubleshoot the stack.

How we support

Ongoing support, upgrades and continuous testing are available as a retainer after handover, agreed separately in writing.
Upgrade work covers reviewing each Medusa release and its migrations before applying them to your environment.
Confirm with us in the quote which support levels, response expectations and testing cadence the retainer includes.

Migrate from Salesforce Commerce Cloud to Medusa