Magento to VTEX migration: what moves, what breaks, and how to sequence it

VTEX solves all three, but only if the migration is sequenced correctly. Get the order wrong and you're debugging catalog import failures at 2am the night before go-live, or watching your organic rankings erode because redirect mapping was treated as an afterthought. This guide gives senior engineering teams the exact playbook: what transfers cleanly, what requires manual intervention, and the three architectural decisions you must make before a single API call.

TL;DR: What moves, what breaks, and 3 decisions to make first

The VTEX Catalog API accepts product data, but three decisions made before your first API call determine whether the migration takes four months or nine: VTEX IO vs. Legacy storefront, headless vs. FastStore, and phased traffic cutover vs. hard launch day.

In our experience scoping VTEX migrations for mid-market and enterprise Magento merchants, the typical store carries 20-60 extensions and 30-40% have no direct VTEX equivalent, that gap register determines timeline more than data volume. What moves cleanly: catalog (via VTEX Catalog API), customer records, and CMS content. What breaks or needs custom work: extension-dependent business logic, Magento's nested URL slug patterns (which require a full 301 redirect mapping audit before cutover), and order history, which VTEX does not treat as live transactional data, historical orders migrate as a read-only archive, not into the active OMS (VTEX Community — Importing historical and in-flight orders when migrating to VTEX). Adobe Commerce 2.4.5 extended support ends August 11, 2026, per Adobe's official release lifecycle documentation, so if your store runs that line, the sequencing decision is already urgent.

Three decisions to make before anything else:

1. VTEX IO vs. Legacy, IO is the current development framework; Legacy requires a planned migration path of its own within VTEX.
2. Headless vs. FastStore, headless gives your team full front-end control via VTEX IO; FastStore is the managed storefront option with faster time-to-launch but less flexibility.
3. Phased cutover vs. hard launch, phased lets you validate the VTEX Catalog API integration and 301 redirect mapping under real traffic before full decommission of Magento. Each of these decisions mirrors the broader challenge of modernizing without disrupting operations, a sequencing problem that applies across platform migrations at any scale.

Why teams are leaving Magento now: EOL dates and PCI risk

Adobe Commerce 2.4.5 extended support ends August 11, 2026, the same date regular support for 2.4.6 expires (Adobe Commerce - Experience League (Release Versions)). Teams still running either version after that date operate an unsupported platform with no security patches forthcoming.

The Adobe Commerce Software Lifecycle Policy sets these deadlines without ambiguity: 2.4.4 extended support already ended April 14, 2026. Merchants on Magento Enterprise (Adobe Commerce) 2.4.5 or 2.4.6 now have weeks, not quarters, before they cross into unsupported territory. Magento 1 has been fully end-of-life since June 30, 2020, no patches, no exceptions (Adobe — Support for Magento 1 software ends June 30, 2020).

The PCI DSS dimension makes this harder to defer. The PCI Security Standards Council is explicit: running software that no longer receives security patches in a cardholder data environment requires compensating controls or remediation. Staying on an unsupported Magento version does not automatically fail a QSA audit, but it creates a documented gap that your acquiring bank and QSA will want closed.

The support cost picture adds a second pressure. Backporting security fixes and maintaining custom extension bridges against an unsupported Magento core does not get cheaper, it compounds. A VTEX migration decided now, with the August 2026 gate in view, can be scoped and sequenced rather than forced.

Magento vs. VTEX architecture: Hosting, TCO, and headless capability

VTEX is a fully managed SaaS platform: there is no server provisioning, no Magento Enterprise patch cycle, and no hosting contract to negotiate. That single architectural shift changes the total cost of ownership calculation more than most teams expect before they start scoping a VTEX migration.

Magento's self-hosted or cloud-hosted model hands infrastructure responsibility to your team: PHP version pinning, Redis configuration, Elasticsearch clusters, and the extensions that bridge gaps in core functionality. A typical Magento store carries between 20 and 60 installed extensions; in our experience auditing pre-migration stores, 30-40% of those extensions have no direct VTEX equivalent, which means the TCO comparison must account for rebuilding that logic, not just switching platforms. Sequencing this infrastructure transition without service interruption is a challenge in itself, teams migrating while continuing to trade should review proven approaches to staying operational during migration before finalising a cutover plan.

VTEX IO, VTEX's cloud-native development platform, is where that rebuild happens. VTEX IO runs on a proprietary framework (Typescript-based, React on the frontend) and replaces the extension/module model with apps deployed to VTEX's own infrastructure: no separate CDN contract, no container orchestration. For teams that need a fully decoupled front end, VTEX FastStore is the headless storefront framework: a Next.js-based layer that connects to VTEX's commerce APIs and is built as a Jamstack toolkit specifically to hit Core Web Vitals targets that legacy Magento themes rarely achieve out of the box.

The practical tradeoff: VTEX IO accelerates storefront iteration but requires learning a platform-specific toolchain. Teams comfortable with React and GraphQL adapt quickly; teams with deep PHP/Magento extension expertise face a steeper transition. Our view is that the elimination of infrastructure overhead justifies the retraining cost for most mid-market merchants, particularly those facing the August 2026 Adobe Commerce support gate.

What data actually migrates: Supported entities, limits, and manual steps

Not all Magento data has a clean path into VTEX: knowing which entities migrate via API, which require transformation, and which need manual handling is the first step in scoping the project accurately.

The attribute set gap is the most underestimated mapping problem. Magento's attribute sets are flat, configurable collections of EAV attributes. VTEX organizes the equivalent metadata as Specifications grouped under Specification Groups, attached at the category level, a structurally different model. In our experience scoping migrations for mid-market merchants, every Magento attribute set requires manual mapping to a VTEX Specification Group before a single SKU entity hierarchy record can be created.

Order history deserves its own decision: treat it as a data integrity and reporting problem, not an OMS migration. We recommend exporting Magento order records to a read-only data warehouse or BI layer and surfacing them through customer service tooling, not importing them into VTEX's live order graph, which is designed for current transactional data only.

VTEX Catalog API ingestion: Category → Brand → Product → SKU sequence

The VTEX Catalog API enforces a strict parent-first insertion order: you must create a Category before a Brand, a Brand before a Product, and a Product before any SKU. Both a valid CategoryId and BrandId are required fields to create a product, there is no deferred-reference resolution in the API (VTEX Developers — Managing products).

The sequence maps to three distinct endpoint calls on developers.vtex.com:

1. `POST /api/catalog/pvt/category`, establish the category tree first; VTEX uses integer IDs, not slugs, so every Magento attribute set hierarchy must be pre-mapped to VTEX category IDs before any product record is written.
2. `POST /api/catalog/pvt/brand`, brands are a flat list in VTEX, not nested; Magento manufacturer attributes collapse here cleanly.
3. `POST /api/catalog/pvt/product`, requires brandId and categoryId resolved from the two prior steps.
4. `POST /api/catalog/pvt/product/{productId}/sku`, SKU creation references the parent productId.

A middleware data transformation layer is not optional. Magento's attribute set model, where a clothing attribute set carries size and color specs that a hardware attribute set does not, has no direct equivalent in VTEX's specification sheet structure. The middleware must translate each Magento attribute set into VTEX Specification Groups and Fields before the product payload is valid.

In our experience migrating mid-market merchants, the attribute set translation step is where catalog imports stall in production. Teams that pre-validate specification group completeness in a staging account before running the full product import cut failed-batch rates significantly. We cover the full VTEX Catalog API entity hierarchy, including specification sheets and SKU attachments, in our PIM - VTEX integration guide.

How order history migration works: The read-only archive pattern

Order history archive migration into VTEX OMS works as a read-only reporting pattern, not a live transactional import, and understanding why saves teams from a costly re-architecture mid-project.

VTEX OMS treats every order record as an active entity within its fulfillment state machine. Injecting historical Magento orders into that live feed would trigger workflow events, inventory recalculations, and notification hooks against data that has already been fulfilled. The integrity of the OMS pipeline depends on orders entering through the standard checkout or API order-creation flow, not through a bulk backdoor import.

The pattern we recommend, and have used on Magento Enterprise migrations, is a parallel archive store: export Magento order history into a read-only data layer (a dedicated database or data warehouse), then surface it to authenticated customers via a VTEX IO custom app or a lightweight API proxy. Customers see their full order history through a consistent store interface; VTEX OMS never touches it.

For customer-facing access, the custom app queries the archive by customerId, renders past orders with order date, line items, and status, and presents them alongside native VTEX orders in a unified order history page. The join key is typically email address, validated against VTEX Customer Data import records to ensure clean identity matching.

SEO redirect strategy: Exporting slugs, building the map, and submitting to GSC

301 redirect mapping is the most traffic-critical step in any VTEX migration, and Magento's URL structure creates specific mismatches that generic redirect tooling won't catch automatically.

Magento stores URL keys at the product and category level independently, generating patterns like `/category-name/product-name.html` for PDPs and `/category-name.html` for PLPs. VTEX uses a different binding config: product URLs derive from the department/category tree you define in the Catalog API, typically resolving as `/department/category/product-name/p`. The.html suffix disappears entirely. That structural difference means a flat find-and-replace won't work, you need a slug-by-slug export before cutover.

The sequence we follow on Magento-to-VTEX projects:

1. Export Magento URL keys via eav_attribute + catalog_product_entity_varchar joins, or through the Magento REST API (`/V1/products?fields=sku,custom_attributes`). Pull both PDP and PLP slugs in a single pass, mixing them up later adds hours to QA.
2. Map to VTEX destination URLs by running the exported slugs against your VTEX department/category tree post-import. VTEX generates canonical URLs after the product tree is live, so this step can only be validated after your catalog data is in place.
3. Load the redirect map into your CDN or reverse proxy layer (Nginx, Cloudflare Rules, or VTEX's own Rewriter app in VTEX IO). Rewriter handles per-URL overrides cleanly for smaller maps; for large migrations with thousands of redirect rules, CDN-level handling avoids the latency overhead of routing every request through an IO app first.
4. Validate a sample, minimum 5% of high-traffic URLs, before DNS cutover. Check both response code (301, not 302) and final destination URL integrity.
5. Submit the updated sitemap to Google Search Console within 24 hours of cutover. GSC's sitemap resubmission signals the index to re-crawl the new URL structure; without it, expect two to four weeks of ranking volatility on affected pages.

One pattern we flag consistently: Magento Enterprise stores that used custom URL rewrites through the url_rewrite table carry redirect chains, a PDP that was reorganized mid-lifecycle may have three or four hops before resolving. Export and clean those chains before building your VTEX map, or you'll embed the chains into the new redirect config and compound page-load latency post-migration.

For the general redirect-mapping framework, including how to prioritize URLs by organic traffic tier and sequence redirect validation alongside phased cutover, see our legacy ecommerce modernization guide.

Custom extension audit: Building the functional gap register before you start

A custom Magento extension audit is the first concrete output your VTEX migration needs, without it, scope risk stays invisible until cutover.

In our experience migrating mid-market Magento and Magento Enterprise stores, a typical installation carries between 20 and 60 extensions. Roughly 30-40% of those extensions have no direct VTEX equivalent, not because VTEX lacks the capability, but because the functionality lives in a different architectural layer, often baked into the platform core or handled via VTEX IO apps rather than a third-party module.

We structure every audit output as a four-column gap register:

The four actions are: native VTEX feature (no build required), VTEX IO app (marketplace or custom IO app), custom rebuild (net-new development), and deprecate (functionality no longer justified). Extensions that fall into the rebuild column drive the majority of migration budget variance, identify them before you sign off on scope, not after your first sprint review.

In practice, the rebuild column surfaces predictable categories. Custom SOAP-based ERP connectors built for older Oracle ATG or legacy order management integrations rarely map cleanly to VTEX's REST-first API model and almost always require a middleware rebuild. Multi-warehouse inventory modules are another recurring example: Magento extensions that handle split-fulfillment logic often duplicate capabilities that VTEX handles natively through its logistics framework, meaning the extension is a deprecation candidate rather than a rebuild, but teams discover this only during the audit.

A third common finding involves B2B quoting workflows built as custom Magento extensions that predate VTEX's native B2B suite. In a typical Magento-to-VTEX migration audit, these account for one to three rebuild-column line items on their own, each carrying a four-to-eight-week development estimate. Identifying all three categories before sprint planning begins is what keeps a VTEX Magento migration on schedule and on budget.

Migration sequencing and realistic timeline for Magento-to-VTEX projects

A VTEX migration from Magento runs 10-20 weeks end-to-end for a mid-market store, with the timeline driven more by extension gap count than by catalog volume.

Stores with fewer than 15 unmatched extension gaps typically land in the 10-13 week band. Stores with 25+ gaps, common on Magento Enterprise installations that grew organically over five or six years, regularly push past 18 weeks once custom middleware data transformation work is factored in.

That pattern is consistent across Magento-to-VTEX projects of similar complexity. catalog data transformation work introduces its own layer of complexity that compounds these timeline pressures, as product attribute mismatches and taxonomy gaps require careful remediation before import.

The order history archive deserves a separate planning line. VTEX does not ingest historical orders as live transactional records; in our experience, teams that try to force a full order-history import into the VTEX OMS mid-migration lose two to four weeks debugging entity mismatches. We scope this as a read-only reporting migration from the start: export the archive, validate data integrity, load it into a BI layer, and keep it out of the VTEX order management flow entirely. Teams coming from platforms with complex legacy order schemas, including Oracle ATG and similar enterprise commerce systems, face compounded remediation effort here because their historical order data structures rarely map cleanly to VTEX entities without an intermediate transformation step.

If your store is on Adobe Commerce 2.4.5, the August 2026 extended support end date is a hard gate, not a soft pressure (Adobe Commerce Software Lifecycle Policy). Adobe Commerce 2.4.5 extended support ends August 11, 2026 That deadline compresses the parallel-run phase, plan for a 12-week maximum, not 15 (Adobe Commerce - Experience League).

For teams comparing VTEX against a Shopify migration or a BigCommerce migration at the planning stage, the sequencing logic here is VTEX-specific; the general phased-cutover framework we use across platforms is covered in our legacy ecommerce modernization guide.

Pre-migration and post-cutover checklists

Use these two checklists as gate criteria, nothing advances until each item is checked off.

Pre-migration: Source audit and VTEX environment provisioning

• [ ] Extension audit complete, catalog all Magento extensions (typical store carries 20-60); flag the 30-40% with no direct VTEX equivalent for custom build or drop decisions
• [ ] Magento URL slug export, extract full URL structure (category, product, CMS pages) to drive 301 redirect mapping; validate patterns before building redirect rules
• [ ] Catalog entity hierarchy mapped, confirm Category → Brand → Product → SKU order required by VTEX Catalog API before any import begins (see VTEX Catalog API mechanics)
• [ ] Customer data export validated, export customer records in format compatible with VTEX Customer Data import; verify PII field mapping and GDPR/PCI DSS compliance before transfer
• [ ] Order history archive decision made, confirm orders migrate as read-only archive, not live OMS data; scope reporting destination (data warehouse, BI tool, or VTEX custom app)
• [ ] PCI DSS compliance window confirmed, if still running Magento 2.4.5 or 2.4.6, note that extended support ends August 11, 2026; unsupported software in cardholder data environments creates immediate PCI DSS scope risk
• [ ] VTEX IO workspace provisioned, development and staging workspaces created; CI/CD pipeline connected
• [ ] Shopify, BigCommerce, or Volusion migration patterns reviewed if applicable, if store previously migrated from another platform, carry forward any existing redirect chains rather than rebuilding from scratch

Post-cutover: QA gates before traffic handover

• [ ] 301 redirect map live and tested, spot-check top 50 traffic URLs from Magento against VTEX routes; zero 404s on pages with inbound links
• [ ] Google Search Console sitemap submission, submit updated XML sitemap within 24 hours of DNS cutover; monitor crawl errors for 72 hours post-launch
• [ ] VTEX Catalog API entity count reconciled: product, SKU, and category counts in VTEX match exported Magento totals; flag discrepancies before removing Magento read access
• [ ] VTEX Customer Data import verified, sample 50-100 customer records; confirm login, saved addresses, and order history visibility
• [ ] Checkout and payment flow end-to-end tested, complete a real transaction in production before full traffic switch
• [ ] PCI DSS re-attestation scoped, confirm new VTEX environment is in scope for next QSA assessment; retire Magento infrastructure from cardholder data environment formally
• [ ] Order history archive accessible, confirm read-only order data is queryable by CS team before Magento decommission

Frequently asked questions

Ready to scope your Magento-to-VTEX migration?

A custom Magento extension audit is the right starting point for any VTEX migration: before you touch catalog import, customer data, or VTEX IO storefront build scope, you need a clear gap register showing which of your store's extensions have no direct VTEX equivalent and which require a custom bridge. In our experience, that audit shapes every sequencing decision that follows.

If your team is on Adobe Commerce 2.4.5 with an August 2026 support deadline closing in, or evaluating VTEX against Shopify, BigCommerce, or Volusion, we can help you scope what a clean move actually requires: catalog, order history archive, 301 redirect mapping, and all. Talk to our team to validate your migration data and timeline.