Migrating from Magento to Medusa: a commerce-first guide

Magento is a commerce platform, so a Magento migration starts with commerce data. The catalogue, checkout, customer accounts, orders, fulfilment, payment, tax, search, and store operations decide the target architecture before the CMS question appears.

For most exits, the clean destination is Medusa as the commerce engine. Payload belongs beside it when the store carries editorial pages, buying guides, campaign landing pages, localization, draft review, or structured content that should not live inside the product catalogue.

This guide covers the migration mechanics for Adobe Commerce and Magento Open Source. It pairs with our Medusa vs Shopify marketplace comparison, but the job here is narrower: moving a Magento store into a Medusa-led commerce build without losing catalog structure or search value.

The move breaks into these workstreams:

Stage	Source work	Target decision
Edition	Identify Adobe Commerce, Adobe Commerce on Cloud, Adobe Commerce as a Cloud Service, or Magento Open Source	Separate contract, support, hosting, and API constraints before scoping
Catalogue	Export products, attributes, variants, categories, media references, pricing, and stock sources	Map to Medusa products, variants, options, categories, collections, tags, inventory, and pricing
Customers	Export customer accounts and addresses	Decide account continuity, registration flow, address migration, and password reset policy
Orders	Read current and historical orders through APIs, reports, or Adobe Commerce archive export where available	Import operational history only where the new store needs to act on it
Extensions	Inventory modules, themes, language packages, checkout customizations, and third-party integrations	Rebuild, replace, or retire each behavior in Medusa, Payload, the storefront, or an external service
URLs	Export category paths, product URL keys, CMS page paths, and URL rewrites	Preserve paths where possible and build redirects before launch

Adobe Commerce and Magento Open Source are separate sources

Adobe says Magento commerce solutions have evolved into Adobe Commerce and Magento Open Source. That matters during migration planning because the code family overlaps, but the operating pressure is different.

Adobe Commerce projects carry Adobe contract, cloud, and support questions. Adobe’s own pages position Adobe Commerce around enterprise scale and cloud capability, while the order archive documentation marks archived orders, invoices, shipments, and credit memos as an Adobe Commerce feature that is unavailable in Magento Open Source.

Magento Open Source projects carry self-managed hosting, upgrade, extension, and support questions. Adobe describes Magento Open Source as a free ecommerce platform with essential tools for creating a digital storefront. The migration audit should name the source edition before it names the destination stack.

Export the catalogue first

The Magento catalogue is the center of the migration. Adobe Commerce Admin can export data under System > Data Transfer > Export, with CSV as the export format. The documented export entity types include Products, Advanced Pricing, Customer Finances, Customers Main File, Customer Addresses, and Stock Sources.

Start with Products. Adobe’s CSV documentation says a full product export contains information about each product in the catalogue and the relationships between them. A row with a value in the SKU column starts a product record, and the next row with a SKU starts the next product. Additional rows can carry multiple images or product options.

That shape matters when a Magento configurable product moves to Medusa. Adobe’s configurable product example says the CSV contains one row for the configurable product and separate rows for each simple variation, with product_type marking the association. Medusa’s product import uses one CSV row per product variant, so the transform needs to group Magento parent and child rows before creating or updating Medusa products.

Build the initial catalogue map around these fields and behaviours.

• Magento simple products, configurable products, grouped products, bundle products, virtual products, downloadable products, and Adobe Commerce gift cards.
• SKUs, product names, descriptions, attribute sets, custom attributes, category assignments, media references, price data, advanced pricing, stock sources, and product status.
• Medusa products, variants, options, categories, collections, tags, inventory links, price sets, sales channels, and shipping profiles.
• Catalogue items that rely on extension-owned fields or custom PHP logic.

Do not start by copying every Magento attribute. Start by grouping the attributes into commerce needs: buyer-visible product information, merchandising filters, fulfilment requirements, pricing logic, inventory ownership, integrations, and content fields that Payload should own.

Map Magento products into Medusa

Medusa’s Product Module handles products, variants, options such as color or size, product organization through categories and collections, tags, bundled and multi-part products, and tiered pricing with price rules. It also links products and variants to other commerce modules, including inventory, pricing, fulfilment, order line items, sales channels, and translations.

Most of the catalogue work comes down to these mappings:

Magento source	Medusa target
Simple product	Product with one variant, or a variant under a grouped target product
Configurable product	Product with options and variants
Bundle product	Bundle or multi-part product behavior, with custom logic where the bundle rules exceed Medusa’s default product model
Grouped product	Product grouping, collection, or storefront composition, depending on how it sells
Virtual or downloadable product	Product configured for the right shipping and inventory behavior
Category tree	Product categories, collections, navigation data, and route mapping
Attribute set and custom attributes	Product options, filters, metadata, custom data models, or Payload content fields
Product media	Media migration into the chosen asset storage, then references from Medusa or Payload

The import should be replayable. Store the Magento SKU and source IDs in the migration data, write a mapping table from Magento records to Medusa records, and make product writes converge on rerun. Medusa’s Admin import can create or update products from CSV. Custom scripts are better once the source relies on category trees, extension fields, external inventory, or rules that need Medusa workflows.

Decide what order history needs to do

Orders and customers should not be treated as one export file. Adobe’s general Data Transfer export list includes customer and stock entities, but orders are not in that list. Adobe’s REST documentation covers Adobe Commerce and Magento Open Source APIs and lists order lifecycle operations in its order processing tutorial. For Adobe Commerce, the order archive feature can move orders, invoices, shipments, and credit memos into archive views, keep them available in Admin, and export archived data as CSV.

Answer the order and customer policy before import.

Current customers usually need continuity: account records, contact details, addresses, group logic, and the new login flow. Medusa’s Customer Module stores and manages guest and registered customers, supports customer groups, and exposes customer management through Admin and APIs. Medusa Admin also states that passwords are not edited from the Admin; customers reset them from the storefront, so authentication migration needs its own policy.

Order history needs a product decision. Medusa’s Order Module manages orders, draft orders, adjustments, tax lines, returns, edits, exchanges, and claims. Its order concepts documentation describes an order as a purchase with purchased items, the customer, payment information, and shipping information. That is enough for active orders and current customer support flows, but it does not mean every historical record should become an editable Medusa order.

Carry the history that the new store needs to use.

• Open orders, returns, exchanges, claims, and support cases that must remain operational after launch.
• Recent customer-facing order history when account self-service depends on it.
• Loyalty, credit, segmentation, or support data that affects the new storefront.
• Reporting data that has no trusted home outside commerce.

Archive the history that only needs retention.

• Closed orders that finance, accounting, or an ERP already owns.
• Old invoices, shipments, refunds, and credit memos that must remain searchable but do not need Medusa workflows.
• Adobe Commerce archive exports where that feature exists.
• Raw Magento database snapshots and API exports kept for audit, rollback, or compliance review.

The migration should state this policy before import scripts are written. Otherwise the team spends time recreating historical state that the new store will never operate on.

Rebuild extensions as commerce code

Magento extensions do not port to Medusa. Adobe’s extension docs define extensions as code that extends or customizes Adobe Commerce behavior, including modules, themes, and language packages. The PHP architecture docs say modules contain PHP and XML files such as blocks, controllers, helpers, and models related to a business feature.

Treat the extension inventory as a rebuild plan.

Magento extension role	Medusa-era replacement
Product or pricing logic	Medusa module, workflow, or pricing customization
Checkout step, payment behavior, or fulfilment rule	Medusa workflow, provider integration, or custom API route
ERP, PIM, CRM, search, or tax integration	Custom module or third-party connector around Medusa events and workflows
Theme or storefront component	Next.js storefront code
CMS page widget or editorial block	Payload collection, block, or rich text model
Admin-only operational tool	Medusa Admin extension or internal tool
Abandoned marketing extension	Remove from scope and redirect any public URL it created

Medusa’s module docs describe custom modules as packages for a single domain or integration. Its plugin docs describe reusable packages that can include modules, API routes, workflows, workflow hooks, links, subscribers, scheduled jobs, and Admin extensions. Use a module for project-specific business behavior. Package it as a plugin only when the customization should be reused across projects.

Put Payload beside Medusa when content needs a CMS

A Magento store often contains CMS pages and content-heavy category pages because Magento was the system the merchant already had. Moving commerce to Medusa does not require every content surface to become commerce data.

Payload fits beside Medusa when editors need collections, draft review, preview, rich text, localization, or reusable blocks. Payload collections define documents and fields in code, and its rich text field stores editor content as JSON. That makes it a better place for buying guides, landing pages, brand content, campaign pages, and editorial SEO surfaces that outgrow product descriptions.

Keep the architecture clear with three ownership boundaries:

• Medusa owns products, variants, pricing, inventory, carts, orders, customers, payments, tax, fulfilment, and commerce workflows.
• Payload owns pages, posts, buying guides, campaign content, editorial blocks, draft workflows, and content relationships.
• The storefront renders both through one front end, with route ownership decided before redirects are generated.

This is the same commerce-first architecture behind the Medusa cluster on this site. The Magento guide should feed that cluster. It should not force Magento into a CMS-only migration story.

Preserve category trees and URLs

Magento migrations can lose search value through URL drift. Adobe’s catalog configuration includes product URL suffix, category URL suffix, category paths inside product URLs, permanent redirects when URL keys change, and generated category/product URL rewrites. Adobe’s URL rewrite docs also say the URL rewrites tool can change URLs associated with products, categories, or CMS pages, and that Commerce creates permanent redirects by default when URL rewrites are created.

Export the URL set before the new storefront owns routing.

• Product URLs, product URL keys, category URLs, category URL keys, and category tree paths.
• CMS page paths that remain content pages.
• URL rewrites for products, categories, CMS pages, and custom rewrites.
• Canonical metadata, sitemaps, hreflang or locale routes, and robots rules where the store uses them.
• Top linked, top clicked, and top revenue URLs from analytics and Search Console.

The redirect plan should be decided in the same mapping table as the data migration. A product that keeps its route gets parity testing. A product that moves gets a 301. A retired product, category, or CMS page gets a deliberate removal decision. Category trees need extra care because Magento can include category paths in product URLs, creating several possible paths to the same product.

What does not export cleanly

Adobe’s export tools move the data out; everything below has to be rebuilt before Medusa can run the store.

• PHP modules, Composer packages, themes, layout XML, templates, and Admin customizations.
• Extension-owned product fields that have no target rule yet.
• Checkout behavior, payment-provider behavior, tax rules, fulfilment rules, and fraud rules.
• Storefront components and theme logic.
• Search, merchandising, personalization, reviews, loyalty, subscriptions, B2B, or marketplace behavior added by extensions.
• Historical operational state that Medusa should not operate on after launch.
• Editorial page structure that belongs in Payload.

The migration plan should price this inventory. The catalogue import is only one workstream.

A pragmatic checklist

Use this checklist to make the migration reviewable:

• Identify whether the source is Adobe Commerce, Adobe Commerce on Cloud, Adobe Commerce as a Cloud Service, or Magento Open Source.
• Export products, advanced pricing, customer files, customer addresses, customer finances, and stock sources where those entities apply.
• Pull orders through the appropriate API, report, archive export, or retained source system.
• Group Magento configurable products and simple variations before writing Medusa products and variants.
• Map product types, category trees, attributes, media, pricing, inventory, and sales channels.
• Decide the customers and orders that need to operate inside Medusa after launch.
• Inventory every Magento extension, theme, checkout customization, and integration.
• Rebuild commerce behavior in Medusa modules, workflows, providers, API routes, subscribers, or Admin extensions.
• Move content-heavy pages into Payload when editors need structured content, drafts, or rich text.
• Build the URL map before cutover and test product, category, and CMS page redirects in staging.

When to stay on Magento

Staying put can be the better move when the store is stable, the extension stack is maintained, the team knows the platform, and the migration would only recreate the same commerce behavior in a different codebase.

The case for Medusa starts when the Magento build has become hard to change: extension risk blocks upgrades, checkout logic needs ownership, marketplace or B2B behavior sits outside the default model, or the team wants commerce modules in a TypeScript stack. Payload enters when content operations have outgrown Magento’s CMS surface.

How WAYF can help

WAYF builds Medusa commerce platforms and Payload content platforms. If you are planning a Magento exit, we can scope the catalogue, customer and order history, extension rebuilds, URL map, and the places where Payload should sit alongside the commerce engine.

Start with Medusa.js development or book a call. We will tell you what should move, what should be archived, and what should be rebuilt.

FAQ

Should a Magento migration go to Medusa or Payload? The commerce engine belongs in Medusa. Payload is added where the store has content-heavy pages, editorial workflows, previews, or structured CMS content that should sit outside the commerce catalogue.

Can Magento products be exported to Medusa? Yes. Adobe Commerce exports product data as CSV, and a full product export includes catalogue records plus relationships between them. Medusa can import products from CSV, with one row per product variant, or receive catalog data through scripts that use Medusa modules and workflows.

Can order history move from Magento to Medusa? It can, but it should be scoped deliberately. Current customer-facing history can move when account self-service, returns, exchanges, claims, or support need it. Finance, shipment, invoice, and refund history can also stay in Magento, Adobe Commerce archive, an ERP, or another system of record when the new storefront does not need to operate on it.

Do Magento extensions migrate to Medusa? No. Magento extensions are PHP components such as modules, themes, and language packages. A Medusa migration inventories each extension and maps it to a custom module, workflow, provider integration, storefront component, Payload content model, or retirement.

How do you preserve Magento SEO during a Medusa migration? Export the live URL set, category paths, product URL keys, and URL rewrite rules before cutover. Then keep paths where possible, issue 301 redirects for moved URLs, remove abandoned pages deliberately, and test category and product trees against the legacy store.

Sources

• Adobe, Magento transitions to Adobe Commerce
• Adobe, Magento Open Source
• Adobe Commerce, Export data
• Adobe Commerce, CSV data files
• Adobe Commerce, Import configurable products
• Adobe Commerce, Create a product
• Adobe Commerce, URL rewrites
• Adobe Commerce, Catalog SEO configuration
• Adobe Commerce, Archive orders
• Adobe Commerce REST API overview
• Adobe Commerce REST order processing tutorial
• Adobe Commerce PHP extensions, module overview
• Adobe Commerce, Manage third-party extensions
• Medusa, Product Module
• Medusa, Import products
• Medusa, Customer Module
• Medusa, Manage customers
• Medusa, Order Module
• Medusa, Order concepts
• Medusa, Commerce Modules
• Medusa, Modules
• Medusa, Plugins
• Medusa, Core Workflows reference
• Payload CMS, Collections
• Payload CMS, Rich Text field
• Payload CMS, Drafts