A populated Magento Open Source catalog does not prove that its sellable structure is complete. Product relationships, scoped values, stock, historical Orders and storefront indexes must agree before records can support the intended buying and operational result.
Each pitfall connects a failure pattern, its warning signs, prevention, an illustrative test and a pass condition. Apply it to the agreed migration approach: native functionality does not establish included transfer coverage. Required outcomes need supported migration output or separately scoped implementation, with approved transformations and exclusions recorded.
Pitfall 1: Flattening Product Types
What goes wrong
Magento Open Source supports simple, configurable, grouped, virtual, bundle, and downloadable Products. These types use different parent-child, price, stock, file and cart relationships. Those relationships determine which SKU carries inventory, what the buyer selects and what appears on an Order line. Flattening the types into simple Products can duplicate merchandising content, remove selectable combinations and change purchased-item identity.
Early warning signs
| Early warning sign | What it indicates |
|---|---|
| Parent and child SKUs are not separately listed. | Configurable and composite Product identity is incomplete. |
| Bundle components or grouped Products appear only in descriptions. | Sellable relationships have been reduced to content. |
| Download files and access limits are outside the Product export. | The downloadable Product cannot function from the Product record alone. |
| Configurable options are mixed with ordinary custom options. | Inventory-bearing variants and customer-entered choices are being confused. |
Prevention
Classify source Products by commercial behavior before mapping fields. The Magento preparation checklist helps define the source evidence.
Preserve configurable child links, grouped associations, bundle options, virtual meaning and downloadable files. Identify the exact SKU that carries inventory and appears on Order lines.
Recommendation example
Illustrative sample: choose a configurable Product, a grouped Product, a dynamic bundle and a downloadable Product where those structures are used. Record which entity owns price, stock, weight, media and fulfillment.
Pass condition
Each in-scope reference Product meets its agreed type and retains the applicable child/component links, selectable values, SKU, price source, inventory behavior, downloadable files and historical Order-line meaning.
Pitfall 2: Separating Attributes From Their Sets and Scope
What goes wrong
An attribute gains meaning through connected settings:
- Definition: input type, option vocabulary and required status.
- Assignment: attribute set, group placement and scope.
- Consumers: storefront flags, search and filter settings.
Copying codes and values alone can create duplicate options, empty filters, incorrect Admin forms or overwritten website/store-view values.
Early warning signs
| Early warning sign | What it indicates |
|---|---|
| Similar fields use inconsistent codes or option labels. | Attribute identity will fragment across Products. |
| Attribute-set membership is missing from the source inventory. | Fields cannot be assigned to the correct Product families. |
| Global, website, and store-view values are mixed in one column. | Scope-specific meaning will be overwritten. |
| The source uses extension-created attributes with unknown behavior. | A field may depend on code, indexing, or storefront logic outside the value itself. |
Prevention
Before importing values:
- Preserve the attribute definition and its uses: input type, option IDs/labels, set, group, scope, search/filter use, comparison, visibility and required status.
- Merge synonyms only when they express the same governed vocabulary.
- Require global variation attributes in the configurable Product’s attribute set, with compatible selection inputs; localized descriptions have a separate scope owner.
- Keep native catalog prices at Global or Website scope. Store-view text does not establish independent Product prices.
Recommendation example
Illustrative assignments:
- Color: variation attribute.
- Material: filterable specification.
- Care instructions: store-view content.
Confirm each field’s set, group, scope and storefront behavior.
Pass condition
The reference attributes appear in the intended attribute sets and groups, retain normalized options and scope, and support the correct variation, filter, search, comparison, and admin-editing behavior.
Pitfall 3: Replacing Child SKUs With Custom Options
What goes wrong
Two choices can look similar while requiring different owners:
-
Custom options
These collect a choice or buyer input without creating a separate stock-bearing Product.
-
Configurable variations
These use eligible simple or virtual children without custom options, with their own SKUs and inventory identity.
Mapping stock-bearing variants to custom options loses child identity. Converting personalization into children invents inventory units.
Early warning signs
- A choice has separate stock or SKU but is proposed as a text or dropdown option.
- Engraving or file upload is proposed as a configurable attribute.
- Source variants have distinct images or prices that are attached only to the parent.
- Order lines cannot identify the purchased child SKU.
Prevention
Classify each choice by whether it creates an independently managed sellable unit. Use configurable children for SKU- and stock-bearing variations; retain custom options for noninventory choices and buyer input. Preserve the selected value on historical Order lines.
Recommendation example
Illustrative choices for a shirt:
- Size and color select configurable children.
- Gift wrapping is a priced custom option.
- Engraving is buyer-entered text.
Pass condition
Real variations retain child SKU, price, stock, media, and Order-line identity, while personalization and optional services remain attached to the parent Product and purchased line without generating false variants.
Pitfall 4: Flattening Websites, Stores, and Store Views
What goes wrong
Magento Open Source uses websites, stores and store views for different purposes. Website assignment and commercial context, store root Categories, and store-view content or URLs need their own owners. Review currency and configuration choices at their applicable scope as well. Treating these layers as a single global field can overwrite translations, expose Products on the wrong website or assign an unintended root Category.
Early warning signs
| Early warning sign | What it indicates |
|---|---|
| The source has several domains, languages, brands, or regions. | A single default scope cannot represent the Store architecture. |
| Product descriptions and URL keys differ by storefront. | Store-view content and SEO meaning need separate ownership. |
| Stores use different root Categories or Product selections. | Check website assignment and the intended store/root Category for assortment and browse paths. |
| Website prices or Customer-group contexts differ. | Check configured price and account scope; Customer-group context must remain valid for the intended website. |
Prevention
Create a map for every website, store and store view:
- Separate global Product identity from website assignments and store-view text.
- Preserve source scope codes used by imports, APIs or integrations.
- Keep configurable parent-child associations global, even when availability and localized text differ.
- Give extension-supplied pricing or visibility its own scope owner instead of inferring it from the native hierarchy.
Recommendation example
Illustrative sample: a Product sold on two websites appears through different store root Categories, descriptions and URL keys. Record website assignment, store/root-Category context and each localized value separately; a store-view translation is not a separate Product-to-Category assignment.
Pass condition
The representative Product appears only in the intended websites and stores, uses the correct root Categories and localized values, and does not inherit content or routes from the wrong store view.
Pitfall 5: Treating Category Records as a Finished Browse Experience
What goes wrong
Category rows alone do not recreate a storefront path. Discovery and continuity depend on:
- Structure: root Category, parent-child hierarchy and Product membership.
- Presentation: visibility, menu inclusion and CMS content.
- Routes: URL keys, metadata and URL rewrites.
Early warning signs
- Categories exist in Admin but not in the menu.
- Products are assigned to unexpected branches.
- Source Categories have several historical URLs.
- Landing-page content or internal links are stored separately.
Prevention
Prepare Category structure separately from menu and route behavior:
- Map root Categories by store and identify hidden or landing-page Categories.
- Preserve hierarchy, Product membership, metadata and descriptions.
- Use explicit route mappings for business-critical source paths and their destination rewrites.
Recommendation example
Use one top-level menu Category, one hidden landing Category, and one Category that moved in the hierarchy. Preserve Product membership, destination route, and source redirects for each.
Pass condition
The reference Categories appear in the intended store hierarchy, contain the correct Products and content, and resolve all important source paths to the correct destination without duplicate or unintended routes.
Pitfall 6: Copying Quantity Without Stock Context
What goes wrong
Magento Open Source inventory can use physical sources, stocks, website sales-channel assignments, source quantities, and salable availability. A positive quantity can still produce an unavailable Product when source assignment, stock assignment, status, reservations, or child-product availability is wrong.
Early warning signs
- Several warehouses are summed into one quantity.
- Imported Products remain assigned only to Default Source.
- Configurable parents and children show conflicting availability.
- An ERP or warehouse system remains authoritative but its item keys are missing.
Prevention
Keep physical stock, channel availability and pending obligations separate:
- Preserve source codes, quantities, status, stock assignments, website relationships and external warehouse keys.
- Define whether Magento or another system owns inventory after migration.
- Reconcile outstanding source Orders with opening stock and destination reservation policy so commitments are neither omitted nor counted twice.
Confirm how the actual import path represents history before it can invoke live inventory events. A salable value is not a substitute for on-hand quantity.
Recommendation example
Illustrative samples:
- A SKU stocked at two warehouses.
- A configurable Product with mixed child availability.
Map each source to the stock serving the intended website.
Pass condition
The representative Products retain accurate source quantities, stock and website assignments, child availability, and external inventory keys, producing the intended salable state without collapsing locations.
Pitfall 7: Losing Customer and Order-Time Snapshots
What goes wrong
Customer and Order records can exist while addresses, Customer groups, Product selections, discounts, taxes, shipping, payment references, invoices, shipments, refunds and status history lose their original meaning.
If migration mapping rebuilds an old Order from current Customer details, its original snapshot can be lost.
Early warning signs
- Order addresses are derived from the current Customer address book.
- Configurable, bundle, or grouped lines lose child details.
- Refunds or shipments are exported independently without Order links.
- Customer-group names exist without their historical pricing context.
Prevention
Keep Customer master data separate from Order-time snapshots. Preserve the included evidence:
- Purchased items: line SKU and selected options.
- Transaction snapshot: addresses, totals, discounts, taxes, method labels and status history.
- Documents and references: invoices, shipments, refunds, comments and external transaction IDs.
A historical invoice, shipment or refund records an earlier event; it must not trigger another charge, fulfillment, notification or stock movement.
If the importer uses live sales operations, control those effects and distinguish archived history from outstanding work that will continue in the destination.
Recommendation example
Choose representative Orders that exist in the source:
- Guest purchase.
- Registered-Customer purchase.
- Partially shipped Order.
- Refunded Order containing a configurable Product.
Pass condition
Each in-scope Order remains understandable from its historical snapshots rather than current Product, Customer, price, payment or shipping configuration. Every included shipment, invoice, refund and external identifier remains linked.
Pitfall 8: Treating All Content as a Page Export
What goes wrong
Magento Open Source content can include CMS Pages, CMS blocks, widgets, Product and Category descriptions, media files, metadata, internal links, and store-view-specific routes. A generic page import can preserve text while losing block references, widget directives, media paths, scope, or URL rewrites.
Early warning signs
- CMS content contains directives, widgets, or source media URLs.
- Blocks are reused across several Pages or store views.
- Product and Category descriptions contain hard-coded internal links.
- Meta fields and URL keys differ by scope.
Prevention
Separate the content owners before translating references:
- CMS Pages, blocks and widgets.
- Catalog descriptions, media and metadata.
- Store-view values and rewrite history.
Translate references to the intended destination entity/media IDs. Preserve scope and remove obsolete theme markup without discarding business content.
Recommendation example
Use one CMS Page containing a reusable block and media image, plus one Category landing page with localized metadata and an old URL.
Pass condition
The representative content renders through the correct Page, block, widget, media, and store-view relationships, while internal links and important legacy routes reach the intended destination.
Pitfall 9: Copying Extension Data Without a Consumer
What goes wrong
Extensions and custom modules can own ERP, PIM, loyalty, subscription, marketplace, tax, shipping, search, checkout and reporting data. Their records may depend on code, events, cron jobs, APIs or external taxonomies. Copying rows alone can leave values without a usable consumer.
Early warning signs
- Important fields use module prefixes or custom entity IDs.
- Staff cannot identify the system that updates a field.
- External systems use keys that are absent from standard Magento entities.
- Source workflows depend on scheduled jobs or observers.
Prevention
Use an integration ownership register for every custom entity and field:
- Parent Product, Customer, Order or content record.
- Module or external owner and durable key.
- Update direction and intended destination workflow.
Confirm supported transfer or separately scoped treatment. Exclude abandoned technical residue by agreement; retained historical evidence still needs a governed archive owner.
Recommendation example
Trace one PIM Product ID, one loyalty account, and one marketplace Order reference from source table to destination owner and continuing integration.
Pass condition
Each retained custom record has a governed owner, valid parent relationship and stable identifier. Records for active use must work through their intended consumer; agreed historical archives must remain traceable. No required live process can pass merely because its data was copied or archived.
Pitfall 10: Trusting Stale Indexes and Caches
What goes wrong
Indexes prepare catalog, price, Category, Customer-group pricing and search data for storefront use. Caches retain processed configuration, layout, blocks and pages.
Bulk imports or direct database changes can leave indexes invalid or scheduled work incomplete, so Admin values differ from storefront search, filters, prices or listings. These symptoms also have non-index causes; diagnose the affected relationship before refreshing output.
Early warning signs
| Early warning sign | What it indicates |
|---|---|
| Products exist in Admin but are missing from search or Categories. | Check index freshness alongside website assignment, visibility, stock and Category context. |
| Price or Customer-group changes appear inconsistently. | Check price indexes, intended scope and Customer-group context; also rule out stale cached output. |
| Indexers show reindex required, suspended, or delayed states. | Freshness needs confirmation through the affected index and storefront result. |
| Cache notifications remain after catalog or extension changes. | Customers may still receive an older rendered state. |
Prevention
Assign index and cache responsibilities in the migration runbook:
- Confirm configured indexer modes and, where scheduled, their cron dependency.
- Record which import changes require partial or full reindexing, including custom-import effects.
- Treat cache refresh as a separate operation; it does not rebuild index data.
Use supported import operations or explicitly account for their indexing effects. Then compare the affected Admin and storefront results through Magento validation. A routine refresh cannot repair a wrong assignment or mapping.
Recommendation example
After a representative bulk catalog import, trace one Product through Admin, Category listing, search, filter results, and Customer-group pricing while observing the related index states.
Pass condition
Required indexers and scheduled work reflect the accepted data state, and relevant caches serve current output. Prove representative Product, Category, price and searchable-attribute results in Admin and storefront; a status label alone is insufficient evidence of the buying result.
Cross-Pitfall Prevention Priorities
Resolve structural and ownership failures before treating a display refresh as the remedy. Product relationships, scoped catalog data, stock, historical snapshots, content and extension consumers need coherent evidence. Indexes and caches then control storefront output derived from those records.
| Prevention layer | Required control |
|---|---|
| Product structure | Preserve parent-child, grouped, bundle, downloadable, and custom-option distinctions. |
| Attribute governance | Keep attribute code, option, set membership, scope, and storefront use connected. |
| Store scope | Keep Global/Website price scope, website assignments, store root Categories and store-view content/URLs distinct. |
| Historical snapshots | Preserve the Order-time Customer, Product, address, state, shipment, and refund context. |
| Storefront visibility | Treat indexes and caches as the delivery layer for otherwise correct records. |
If the examples expose required module records beyond supported handling, a Custom Migration assessment can qualify that data requirement. The agreed target code and continuing workflow still need their own implementation and proof.
Conclusion
Product or Customer counts cannot prove Magento Open Source migration quality. Product types, attributes, scope, inventory, Categories, content, Orders and extension records must still support the agreed business outcome.
A coherent destination keeps each relationship at its intended level and historical evidence separate from current configuration. Approve catalog, scope, stock, Orders, routes, custom consumers and storefront freshness together; a populated Store is only the starting point.
Common Questions
Why should Magento Open Source Product types be preserved instead of flattened?
Each Product type defines different parent-child, price, stock, file, and cart relationships. Flattening changes what the buyer selects and what staff can manage or trace on Orders.
What is the practical difference between configurable attributes and custom options?
Configurable attributes select eligible simple or virtual children without custom options, with their own SKUs and inventory identity. Custom options modify or personalize the Product and purchased line without creating independently managed stock units.
Why does attribute scope matter during migration?
Scope determines whether a value is shared or localized. Keep Global/Website catalog prices separate from store-view translations and metadata. Incorrect scope or assignment can overwrite intended values or expose them in the wrong storefront.
Can imported quantity alone prove that a Magento Product is available?
No. Availability can depend on source assignment, stock assignment, status, website relationship, reservations, and child-product state in addition to quantity.
Should old extension data always be copied into custom attributes?
No. Extension records may depend on separate entities, workflows, code, external systems or taxonomies. Active data needs a defined destination owner and working consumer. Agreed historical archives can preserve evidence without recreating a live workflow; they cannot satisfy a process that must continue.
Why can Products appear in Admin but remain missing from the storefront?
Invalid or delayed indexes, incomplete cron processing or stale caches can hide otherwise correct catalog, price, Category and search output. Check website assignment, visibility and stock as well. Refreshing output cannot repair an incorrect relationship, so confirm both the data and its actual storefront result.
Can Magento Open Source store-view translations imply separate Product prices?
No. Store-view descriptions and labels are separate from native catalog price scope, which is Global or Website. Preserve localized text at its intended level and map website pricing according to the actual configuration. If an extension supplies another pricing model, that behavior needs an explicit destination owner and representative buyer-context proof.
Should configurable variation attributes be localized independently in each store view?
Keep the variation-defining attribute identity and parent-child association global. Translated labels and descriptive content can serve localized storefronts without creating a different sellable child relationship. Confirm the configurable attribute set, chosen values, website availability, and purchased SKU together before treating localization as complete.
Can importing old Magento Orders change current inventory or payment behavior?
The risk depends on the import path. A record retained as historical evidence is different from a live sales operation that reserves stock, submits a payment, sends a message, or initiates fulfillment.
Keep completed history from replaying its effects, and reconcile unfulfilled commitments with opening stock and reservation ownership.
Demonstrate the selected path rather than assuming either that every import is harmless or that every import creates reservations.