VTEX migration failures rarely come from one missing field. They emerge when a connected commerce architecture is treated as a simple destination for Products, Customers, and Orders. A record may exist while its SKU relationship, trade-policy context, seller ownership, fulfillment path, Master Data link, or external-system identifier no longer carries the meaning needed by the operation.
The following pitfalls focus on recurring failure patterns. Each one explains what breaks, the signals that expose the problem early, the prevention approach, a practical recommendation, and the condition that proves the pitfall is controlled.
VTEX Pitfall Prevention Map
| Operating area | Hidden failure pattern | Prevention focus |
|---|---|---|
| Catalog | Product records exist but SKU and specification relationships are incomplete. | Preserve the Product–SKU–category–specification chain. |
| Commercial context | A valid price is applied in the wrong sales channel or seller context. | Map price ownership, trade policies, and seller offers separately. |
| Marketplace | Products and Orders lose seller, offer, commission, or fulfillment ownership. | Preserve marketplace and seller relationships, not just labels. |
| Logistics | Inventory totals move without warehouses, docks, carriers, or delivery meaning. | Rebuild the fulfillment network around explicit owners. |
| Orders | Totals remain readable but package, invoice, cancellation, or external references disappear. | Preserve historical transaction context and traceability. |
| Custom data | Master Data and app-owned records are flattened into ordinary Customer fields. | Classify every custom object by schema, relationship, and owner. |
| Integrations | ERP, PIM, WMS, or marketplace systems reconnect with broken IDs or update direction. | Preserve identifiers and establish one authority per data domain. |
| Storefront | Catalog presence is mistaken for complete search, checkout, and content behavior. | Assign storefront and checkout implementation separately from migrated records. |
Pitfall 1: Treating VTEX as One Self-Contained Store
What goes wrong
The migration is designed as though VTEX were one database and one storefront. In practice, Catalog, Pricing, Promotions, Checkout, Orders, Inventory and shipping, marketplace relationships, Master Data, storefront implementation, and external systems can each own part of the operating model. Records may look correct in one module while another module applies different availability, price, seller, or fulfillment behavior.
This creates false completeness. The team approves Product and Order counts even though nobody can explain which system controls the values that customers and operations will actually use.
Early warning signs
| Warning sign | Likely consequence |
|---|---|
| Scope lists only Products, Customers, and Orders. | Trade-policy, seller, logistics, or custom-data dependencies remain invisible. |
| One reviewer approves every data area. | Important context is accepted without the responsible business owner. |
| External systems are described only as “integrations.” | Field ownership and update direction remain undefined. |
| Storefront behavior is expected to follow Catalog records automatically. | Search, content, checkout, and navigation gaps appear after records are loaded. |
Prevention
Model the destination by operating domain. For each important value, identify whether its continuing owner is VTEX Catalog, Pricing, Promotions, Checkout, Orders, Inventory and shipping, Master Data, a seller, the storefront implementation, or an external system. Use one representative scenario that crosses several domains so handoffs become visible.
Recommendation example
Trace a high-value SKU from Catalog through its specification, price context, seller or first-party ownership, inventory location, delivery promise, checkout selection, Order creation, and external back-office identifier. The same scenario should have named reviewers from merchandising, commercial operations, logistics, and integration ownership.
Pass condition
Every launch-critical data domain has one declared owner, and the team can explain how a representative Product moves from Catalog discovery to price, availability, checkout, Order, fulfillment, and external reconciliation.
Pitfall 2: Collapsing Product, SKU, and Specification Meaning
What goes wrong
Source Products and variants are flattened into generic VTEX Product records. SKU-level choices, images, dimensions, stock references, and specification values lose their relationship to the sellable unit. Product specifications may be copied as text even though they should support information or browsing, while SKU specifications needed for buyer selection are attached at the wrong level.
A Product can therefore exist but remain unavailable, hard to find, or impossible to select correctly. The defect is structural rather than cosmetic.
Early warning signs
| Catalog signal | Failure pattern |
|---|---|
| Product and SKU fields are reviewed in one flat sheet. | Sellable variations lose their own identifiers and attributes. |
| Size, voltage, or color values are stored as Product text. | SKU selection and filtering no longer reflect the purchasable unit. |
| Images are preserved only at Product level. | A selected SKU shows the wrong media. |
| Specifications are counted but not classified by purpose. | Search, filters, Product details, or integrations receive unusable values. |
Prevention
Classify each source value as Product data, SKU data, Product specification, SKU specification, media, external identifier, or storefront-only presentation. Preserve the creation and dependency order among categories, specification groups, fields, Products, SKUs, specification values, and SKU files. Do not infer success from the default SKU alone.
Recommendation example
For an appliance available in several voltages and finishes, keep the generic model as the Product, each purchasable combination as a SKU, voltage and finish as SKU-selection values where appropriate, technical information as Product specifications, and SKU-specific images and dimensions with the actual sellable unit.
Pass condition
Representative Product families preserve the correct Product–SKU relationship, selectable differences, specifications, images, identifiers, and active sellable units without relying on flattened descriptive text.
Pitfall 3: Breaking Category and Specification Dependencies
What goes wrong
Categories are copied as navigation labels without preserving how they govern Catalog organization and specification requirements. Specification groups or fields are created after Products and SKUs, attached to the wrong category, or populated with inconsistent values. A late category or specification change can disable SKUs, fragment filters, or leave important Products without required information.
The resulting catalog may contain the expected records while search and Product activation behave unpredictably.
Early warning signs
| Dependency signal | Risk created |
|---|---|
| Category depth is copied without a target browsing model. | Catalog hierarchy becomes harder to maintain and discover. |
| Specification fields are created independently of categories. | Required values and filters differ across related Products. |
| New SKU specifications are added after bulk Product loading. | Associated SKUs may become inactive until values are completed. |
| Equivalent values use inconsistent spelling or units. | Filters split into duplicate or misleading choices. |
Prevention
Design the category and specification model before bulk Product loading. Define which categories require which Product or SKU specifications, normalize controlled values, and preserve the sequence required to create and associate those records. Treat later schema changes as controlled Catalog changes, not casual content edits.
Recommendation example
For an electronics catalog, establish the department, category, specification groups, voltage field, capacity field, and allowed values before creating SKUs. Populate one complete family and verify its active status, filtering, and storefront selection behavior before expanding the pattern.
Pass condition
Categories, specification groups, fields, values, Products, and SKUs form a consistent dependency chain, and representative SKUs remain active and discoverable after the target schema is applied.
Pitfall 4: Moving Prices Without Trade-Policy and Seller Context
What goes wrong
The migration preserves one price per SKU while the real operation differentiates prices, promotions, availability, logistics, or payments by sales channel, trade policy, seller, customer segment, or external pricing authority. A numerically correct value can therefore be commercially wrong in the context where a customer sees it.
Historical promotions may also be mistaken for current configuration, causing obsolete discounts to be rebuilt or active commercial rules to be missed.
Early warning signs
| Commercial signal | Hidden problem |
|---|---|
| Only a base price is compared. | Channel-, seller-, or segment-specific pricing is unaccounted for. |
| Trade policies are discussed after Catalog loading. | Price, promotion, logistics, and payment contexts may require rework. |
| Promotion names are treated as enough evidence. | Conditions, eligibility, and stacking behavior are not preserved. |
| ERP or pricing-engine ownership is unclear. | Migrated values are overwritten or conflict with external updates. |
Prevention
Map commercial context separately from Product data. For each priority SKU, identify the price owner, applicable sales channel or trade policy, seller, promotion dependencies, customer context, and update direction. Preserve historical price evidence only where it remains useful; configure current commercial behavior under its actual target owner.
Recommendation example
Use one SKU sold directly and through a marketplace, with a B2C price, a B2B context, and an active promotion. Document which values enter VTEX, which come from an external service, and which conditions determine the final customer-facing result.
Pass condition
Priority SKUs show explainable price and promotion outcomes in every intended commercial context, with no unresolved conflict between migrated values, VTEX configuration, sellers, and external systems.
Pitfall 5: Losing Seller and Offer Ownership
What goes wrong
Marketplace data is treated as ordinary Product data. Seller identity, offer ownership, SKU matching, price and stock responsibility, commission context, service-level expectations, and fulfillment responsibility are flattened into notes or discarded. Products may appear in the marketplace, but the operation cannot determine who owns the offer or who must fulfill the resulting Order.
This is especially damaging when several sellers offer the same SKU or when a merchant operates as both a marketplace and a seller elsewhere.
Early warning signs
| Marketplace signal | Failure pattern |
|---|---|
| Seller IDs are stored as Product attributes. | Marketplace ownership cannot drive offer and Order handling. |
| Duplicate Products are created for seller offers. | Catalog matching and buy-box behavior become fragmented. |
| Marketplace and seller Orders are reviewed together. | Checkout owner and fulfillment owner are confused. |
| External seller references are dropped. | Reconciliation and connector updates create duplicates. |
Prevention
Separate Catalog identity from seller offer identity. Preserve seller identifiers, SKU matching references, price and quantity ownership, marketplace Order references, fulfillment responsibility, and external connector keys. Define whether the destination account acts as marketplace, seller, or both in each relationship.
Recommendation example
For a branded Product supplied by three sellers, maintain one marketplace Catalog identity and three distinct offers with their seller, price, stock, and delivery ownership. Review an Order that selects one seller and confirm that the correct party receives and fulfills it.
Pass condition
Representative marketplace Products retain accurate seller offers, ownership, matching, price, stock, Order routing, and fulfillment responsibility without creating duplicate Catalog identities.
Pitfall 6: Flattening Inventory and Logistics Into One Quantity
What goes wrong
The migration transfers an available quantity but loses warehouses, inventory records, loading docks, carriers, delivery policies, pickup locations, trade-policy relationships, or external WMS ownership. The storefront may show stock while checkout cannot produce the intended delivery promise, or the wrong location may be treated as the source of fulfillment.
An opening quantity is also unreliable when an ERP or WMS will immediately become the continuing authority.
Early warning signs
| Logistics signal | Operational consequence |
|---|---|
| One total quantity replaces location-level stock. | Availability cannot be allocated to the correct fulfillment point. |
| Inventory loads before logistics relationships exist. | Checkout simulations produce incomplete or misleading delivery options. |
| Pickup and delivery are treated as the same path. | Location and service-level commitments are lost. |
| ERP or WMS updates are not paused or sequenced. | Migrated quantities are overwritten before reconciliation. |
Prevention
Map the fulfillment network, not just stock values. Identify inventory locations, logistics relationships, delivery and pickup paths, external ownership, SKU identifiers, and the sequence for opening inventory and continuing synchronization. Preserve historical shipping labels separately from current delivery configuration.
Recommendation example
For one SKU stocked in two warehouses and available for pickup in selected regions, trace which inventory is offered under each sales channel, which delivery promise appears at checkout, and which system publishes the continuing quantity.
Pass condition
Representative SKUs have accurate location-level availability, explainable delivery or pickup outcomes, and one documented continuing owner for every stock update.
Pitfall 7: Reducing Orders to Totals and Status Labels
What goes wrong
Orders are migrated with an Order number, Customer, total, and generic status, but package composition, seller relationship, item substitutions, shipping data, invoice references, cancellation history, refunds, tracking, external IDs, or marketplace context no longer remains interpretable. Support teams can find the Order but cannot explain what happened.
Historical records may also be mistaken for proof that current Checkout, payment, tax, and fulfillment configuration works.
Early warning signs
| Order evidence | Missing meaning |
|---|---|
| A final total is visible. | Discounts, tax, shipping, refunds, or adjustments cannot be explained. |
| One status is preserved. | The source lifecycle and current business meaning are ambiguous. |
| Product names are readable. | SKU, seller, package, and fulfillment relationships are absent. |
| External references are omitted. | ERP, WMS, marketplace, or accounting reconciliation breaks. |
Prevention
Define the historical use of Orders and preserve the evidence required for support, finance, seller operations, and reconciliation. Include item and SKU identifiers, Customer relationship, seller and marketplace context, financial components, package and shipment data, invoice or tracking references, status history where meaningful, and external keys. Keep live Checkout configuration outside historical Order interpretation.
Recommendation example
Review a direct Order, a marketplace Order, a multi-package Order, a cancelled Order, and a refunded Order. A service agent should be able to explain the items, seller, financial outcome, fulfillment state, and external trace without opening the source system.
Pass condition
Representative historical Orders remain understandable across Customer, SKU, seller, financial, package, invoice, fulfillment, cancellation or refund, and external-system dimensions without reopening the source Platform.
Pitfall 8: Treating Master Data as Ordinary Customer Fields
What goes wrong
Master Data entities, custom schemas, related records, app-owned objects, and external references are compressed into a few Customer or Order fields. Relationships among companies, contacts, approvals, loyalty records, service requests, or operational entities disappear because the source and target schemas are not treated as structured objects.
The visible Customer profile may look complete while workflows and integrations lose the records they actually depend on.
Early warning signs
| Custom-data signal | Risk created |
|---|---|
| Every custom record is described as a Customer field. | Separate entities and one-to-many relationships are lost. |
| Schemas are listed without relationship keys. | Records cannot be connected after loading. |
| App-owned objects are absent from samples. | Operational workflows fail outside standard commerce records. |
| Personal data is copied without an ownership rule. | Privacy, retention, and access expectations become unclear. |
Prevention
Inventory custom objects by schema, primary key, relationship, business purpose, sensitivity, current owner, target owner, and continuing consumer. Preserve only the data that has a valid target use, and keep structured relationships structured. Custom data that remains external should retain the identifiers needed to link it safely to VTEX records.
Recommendation example
For a B2B operation, separate company identity, buyer contacts, role or approval records, commercial references, and Customer profiles. Preserve the keys that connect them rather than concatenating all values into notes.
Pass condition
Every business-critical custom object has an explicit schema, relationship, owner, and target use, with no structured entity hidden inside generic Customer or Order fields.
Pitfall 9: Reconnecting ERP, PIM, and WMS Systems With Broken Identity
What goes wrong
External systems are reconnected using new VTEX IDs without preserving source reference IDs, cross-reference tables, update direction, or event sequencing. The PIM creates duplicate Products, the ERP overwrites prices, the WMS posts inventory to the wrong SKU, or Order updates fail because each system identifies the same record differently.
A technically successful API connection can therefore damage migrated data immediately.
Early warning signs
| Integration signal | Likely failure |
|---|---|
| New VTEX IDs are treated as the only identifiers. | External systems cannot match migrated records. |
| Create and update behavior are not distinguished. | First synchronization duplicates existing objects. |
| Two systems are allowed to write the same field. | Values oscillate or overwrite one another. |
| Historical Orders and live Orders use one undifferentiated feed. | Old records trigger unintended operational processing. |
Prevention
Create an identity and ownership contract for each integration. Preserve source IDs where needed, record VTEX IDs, define create-versus-update behavior, establish one writer per field or domain, and sequence initial synchronization after migrated records are reconciled. Separate historical data from live operational events.
Recommendation example
For a PIM and WMS integration, create a cross-reference for Product, SKU, and inventory identifiers. The PIM may own descriptive Catalog content, while the WMS owns location-level stock; neither should overwrite fields owned by the other.
Pass condition
Each external system updates the intended VTEX record exactly once, uses stable cross-references, and has a documented read/write boundary that prevents duplication and overwrite conflicts.
Pitfall 10: Assuming Catalog Data Creates the Storefront and Checkout
What goes wrong
Catalog records are treated as a complete VTEX customer experience. Search indexing, facets, Product-page components, content, navigation, seller display, cart simulation, Checkout fields, payment, shipping, tax, and storefront integrations remain separate implementation concerns. Products may exist and still be difficult to discover or impossible to buy through the intended path.
The failure is often misdiagnosed as bad migration even when the missing owner is storefront, search, Checkout, or integration implementation.
Early warning signs
| Customer-journey signal | Hidden gap |
|---|---|
| Products are checked only in Admin. | Search, filtering, Product-page, and seller-display defects remain hidden. |
| High-value URLs have no destination map. | Content and organic entry paths lose continuity. |
| Historical payment and shipping labels are reused as configuration. | Current Checkout methods remain unimplemented. |
| Headless or composable components are not assigned owners. | Correct data never reaches the customer-facing experience. |
Prevention
Separate migrated records from storefront and Checkout implementation. Define the search and facet model, Product-page data requirements, content and URL destinations, seller presentation, cart and Checkout contracts, and external services. Use the same representative Product and Order scenarios across Catalog, storefront, and Checkout ownership so gaps cannot hide between teams.
Recommendation example
For a priority Product, confirm that the intended URL resolves, search finds it, filters expose the correct specifications, the right SKU and seller can be selected, cart simulation returns current price and availability, and Checkout receives the required delivery and Customer context.
Pass condition
Priority customer journeys use migrated records correctly across discovery, Product selection, seller context, cart, and Checkout, with every non-data behavior assigned to a named target owner.
Conclusion
VTEX migration succeeds when relationships and ownership survive—not merely records. Product and SKU structure, specifications, trade policies, sellers, logistics, Orders, Master Data, integrations, search, and Checkout must remain connected through explicit identities and responsibilities. The safest prevention pattern is to trace representative commercial scenarios across those boundaries and require a clear pass condition for each recurring failure mode.
Common Questions
Why can VTEX Products exist but remain unavailable to customers?
A Product may still lack an active SKU, required specification values, images, price, inventory, seller offer, trade-policy relationship, or storefront exposure. Availability depends on the connected Catalog and commercial context, not Product presence alone.
What is the most important VTEX Catalog relationship to preserve?
The Product–SKU relationship is central, but it depends on categories, specification groups, Product and SKU specifications, media, identifiers, and active sellable units. Flattening those records removes the structure buyers and integrations use.
Why should trade policies be reviewed separately from prices?
Trade policies can group Catalog, price, promotion, logistics, segmentation, and payment settings for distinct sales strategies. A price can be correct numerically and still apply in the wrong commercial context.
How should marketplace seller data be handled?
Preserve seller identity, offer ownership, SKU matching, price and stock responsibility, Order references, and fulfillment ownership. Seller information should not be reduced to a Product attribute or free-text note.
Does preserving historical Orders prove that VTEX Checkout is ready?
No. Historical Orders preserve transaction evidence. Current Checkout, payment, shipping, tax, promotion, and fulfillment behavior must be implemented under their current owners.
Why are external identifiers critical in VTEX migration?
ERP, PIM, WMS, marketplace, and support systems often use their own identifiers. Stable cross-references prevent duplicate creation, wrong-record updates, and broken reconciliation after those systems reconnect.