Shopware migration pitfalls usually arise when records are transferred without the sales-channel, inheritance, rule, content, and extension relationships that determine how those records behave. A Product can exist in Administration while remaining invisible in a sales channel, a variant can inherit the wrong price or media, and a Shopping Experience can render without the Product or Category links it once displayed.
The failure patterns below focus on those relationship breaks. Each one defines the warning signs, a preventive control, a realistic example, and a pass condition that proves the pitfall has been contained.
Pitfall 1: Importing Products Without Their Sales-Channel Assignments
What goes wrong
Shopware sales channels can represent storefronts, headless API channels, product comparisons, and other destinations. Products, Categories, languages, currencies, domains, payment methods, shipping methods, Customer registration, and themes can differ by channel. Importing the Product without channel visibility can leave it present in Administration but unavailable to shoppers.
Early warning signs
| Early warning sign | What it indicates |
|---|---|
| The source has several domains, regions, brands, or marketplace feeds. | A single default sales channel is unlikely to preserve the operating model. |
| Product availability differs by storefront or channel. | Assortment ownership must be mapped by sales channel. |
| Customers are bound to particular sales channels. | Customer context is not globally interchangeable. |
| Categories or dynamic Product groups are used to populate channel assortments. | Channel visibility depends on relationships beyond the Product row. |
Prevention
Create a sales-channel ownership map. Preserve Product and Category assignment, language, currency, domain, Customer context, payment and shipping relationships, navigation entry, and external channel key. Do not assume every Product belongs to every channel.
Recommendation example
Use one Product available in two storefronts, one Product restricted to a regional channel, and one Product exported through a comparison channel. Represent each channel assignment separately.
Pass condition
Each representative Product appears only in the intended sales channels with the correct language, currency, Category path, Customer access, and channel-specific URL or feed relationship.
Pitfall 2: Flattening Product Variants, Properties, and Inheritance
What goes wrong
Shopware properties can describe Products, support filtering, and generate variants. Variants can inherit price, stock, media, dimensions, text, and other values from the parent until inheritance is removed. Flattening the family can duplicate parent content, lose child Product numbers, or overwrite variant-specific values.
Early warning signs
| Early warning sign | What it indicates |
|---|---|
| Variant combinations are generated from property options but child IDs are missing. | The variant family lacks stable sellable-unit identity. |
| Parent and variants share values in some fields but differ in others. | Inheritance and override boundaries are undocumented. |
| Source data does not identify inherited versus overridden values. | The target may duplicate values or erase intentional differences. |
| Filter properties are mixed with variant-generating properties. | Discovery attributes and sellable combinations are being conflated. |
Prevention
Preserve the main Product, variant-generating properties, option combinations, child Product numbers, inheritance state, exclusions, prices, stock, media, and active status. Keep descriptive filter properties separate from the properties that define sellable variants.
Recommendation example
Use a shirt whose variants inherit descriptions but override Product number, price, stock, and image. Include one excluded color-size combination.
Pass condition
The representative family contains the correct variants and exclusions, inherited fields remain inherited, overridden fields retain child values, and filter properties do not create unintended variants.
Pitfall 3: Recreating Prices Without Their Rule Builder Conditions
What goes wrong
Shopware Rule Builder conditions can influence prices, promotions, shipping, payment, content, and other commercial behavior. Copying only the resulting price or discount removes the Customer group, sales channel, currency, quantity, time, cart, or Order condition that explains when the value applies.
Early warning signs
| Early warning sign | What it indicates |
|---|---|
| Several prices exist for the same Product without a clear audience. | The conditions that select a price are missing. |
| Promotions are described by names but not by conditions and priorities. | Rule Builder logic cannot be reconstructed from labels. |
| Shipping or payment availability depends on Customer or cart properties. | Operational methods are governed by rules, not migrated records alone. |
| Rules reference Customer groups, tags, sales channels, or custom fields. | The rule’s dependent data must remain connected. |
Prevention
Model the rule separately from its result. Preserve rule name, priority, conditions, operators, referenced entities, and the module that consumes the rule. Reassign referenced Customers, groups, or sales channels when source IDs cannot carry over.
Recommendation example
Use one quantity price for a wholesale Customer group and one shipping rule limited to a regional sales channel and cart value. Preserve the conditions and references rather than only the final values.
Pass condition
Each representative rule applies only in its intended context, remains inactive outside that context, and references valid destination Customers, groups, Products, channels, currencies, and custom fields.
Pitfall 4: Treating Category Trees and Dynamic Product Groups as the Same Thing
What goes wrong
Shopware Categories can organize navigation and content, while dynamic Product groups select Products according to rules. A source collection or merchandising group can be mistaken for a permanent Category, or a Category can be rebuilt as a rule that no longer provides hierarchy, content, or routes.
Early warning signs
- Source collections combine manual and rule-based membership.
- A Category exists primarily to display campaign Products.
- Products appear in search but not in the intended navigation branch.
- Dynamic groups depend on properties or custom fields that are not normalized.
Prevention
Classify each grouping by ownership: hierarchy and route, manual Product membership, dynamic selection rule, Shopping Experience, or channel assortment. Preserve the fields used by dynamic groups and the Category relationships used by navigation.
Recommendation example
Represent a permanent “Shoes” Category, a dynamic “Low stock” group, and a seasonal landing Category driven by a dynamic group as three connected but distinct structures.
Pass condition
Permanent Categories retain hierarchy and routes, dynamic groups return the intended Products from valid conditions, and campaign layouts reference the correct grouping without duplicating Product ownership.
Pitfall 5: Copying Shopping Experiences Without Their Assigned Context
What goes wrong
Shopping Experiences can create landing pages, shop pages, Category layouts, and Product-page layouts. Their sections, blocks, elements, media, links, and data assignments depend on the Page type and sales channel. Copying layout content without its assigned Category, Product, or channel can leave an attractive but unreachable or misleading page.
Early warning signs
| Early warning sign | What it indicates |
|---|---|
| Layouts contain Product or Category links that point to source IDs. | Shopping Experience content contains broken internal relationships. |
| Category pages use different layouts by sales channel. | Layout assignment is channel-specific. |
| Product-page elements contain record-specific overrides. | A generic template cannot reproduce all storefront behavior. |
| Landing pages exist without navigation or direct route documentation. | Content may migrate without a usable discovery path. |
Prevention
Preserve layout type, sections, blocks, elements, media, translated content, links, assigned Categories or Products, sales-channel compatibility, and record-level overrides. Replace source IDs with destination entity references.
Recommendation example
Use one Category layout, one standalone landing page, and one Product-page layout with a Product-specific text override. Trace every linked Product, Category, media item, and route.
Pass condition
Each representative Shopping Experience is reachable through the intended route, renders in the correct sales channel and language, and displays valid destination Products, Categories, media, and record-specific overrides.
Pitfall 6: Losing Custom-Field Definitions or Language Inheritance
What goes wrong
Shopware custom fields can extend Products, Categories, Customers, Orders, and other entities. The value depends on a field set, data type, assignment, translation, and template or rule that uses it. Copying values without definitions creates invisible or unusable data. Entering only a translated value can also break inheritance from the default language.
Early warning signs
- Custom-field values exist but the field set is undocumented.
- Several languages contain different or missing values.
- Rules or templates reference technical custom-field names.
- App-created fields are mixed with merchant-created fields.
Prevention
Preserve field-set identity, technical name, label, type, allowed values, entity assignment, default-language value, translated overrides, and every Rule Builder, template, or integration reference. Keep application-owned custom data under its actual owner.
Recommendation example
Use a Product compliance field inherited across languages and a localized marketing label that intentionally overrides the default value.
Pass condition
The fields appear on the correct entities, retain usable definitions and allowed values, inherit from the default language where intended, and remain available to every rule, template, or integration that consumes them.
Pitfall 7: Preserving Order Headers but Losing State, Transaction, and Delivery Context
What goes wrong
Shopware Orders can include Order lines, Customers, addresses, currencies, taxes, discounts, transactions, deliveries, documents, statuses, and external references. Importing only the Order header and total removes the state transitions and operational records that explain payment and fulfillment.
Early warning signs
- Payment and delivery statuses are compressed into one generic Order status.
- Shipments, tracking, refunds, or documents are stored separately.
- Variant child Product numbers are absent from Order lines.
- External ERP or payment references exist only in extension data.
Prevention
Preserve the Order snapshot, line items, variant identity, addresses, totals, taxes, promotions, transaction state, delivery state, tracking, documents, comments, and external IDs. Keep historical state independent from current live rules and methods.
Recommendation example
Use one paid and shipped Order, one partially fulfilled Order, and one refunded Order containing a variant and a promotion.
Pass condition
Each representative Order remains understandable across Customer service, finance, and fulfillment, with valid line, transaction, delivery, document, status, and external-reference relationships.
Pitfall 8: Rebuilding SEO URLs Without Sales-Channel and Canonical Context
What goes wrong
Shopware SEO URL templates and generated paths can differ by sales channel. Products with variants can also use a shared canonical URL or variant-specific paths. Recreating slugs without the template, main Category, historical path, and channel context can produce duplicate pages or redirect visitors to the wrong storefront.
Early warning signs
- The same Product has different paths by sales channel or language.
- Source URLs depend on Category breadcrumbs or main Category assignment.
- Variant pages use mixed canonical behavior.
- Old URLs are not linked to destination routes.
Prevention
Preserve source paths, destination Product or Category, sales channel, language, main Category, canonical setting, and redirect relationship. Rebuild SEO indexes after template changes so generated paths reflect the intended rules.
Recommendation example
Use one Product assigned to two Categories in two sales channels, plus a variant family that uses one canonical Product URL. Record every important source path and intended destination.
Pass condition
The representative routes resolve in the correct sales channel and language, canonical behavior is consistent across variants, and legacy paths redirect to the intended current Product or Category.
Pitfall 9: Copying Extension Data Without Its Entity and Lifecycle
What goes wrong
Shopware extensions and applications can add custom entities, fields, rules, API records, scheduled processes, storefront components, payment or shipping data, subscriptions, marketplace links, and integration state. Copying fields into standard entities does not preserve the extension’s lifecycle or references.
Early warning signs
- Technical fields use an app or plugin prefix.
- Custom entities reference Products, Customers, or Orders through internal IDs.
- Staff relies on data that has no standard Administration module.
- An external system updates the value through an API or webhook.
Prevention
Create an ownership map for each extension. Identify its entities, parent references, technical fields, configuration, external IDs, update direction, and continuing destination. Separate historical evidence from live operational state.
Recommendation example
Trace one subscription record, one marketplace listing, and one ERP Product identifier from extension entity to core Shopware record and external owner.
Pass condition
Every retained extension record has a defined destination entity, valid parent references, stable external identifiers, and a continuing application or integration that can interpret and maintain it.
Pitfall 10: Assuming Correct Product Data Automatically Produces Correct Search Results
What goes wrong
Shopware search and indexing can depend on searchable Product fields, Product numbers, keywords, properties, manufacturers, categories, synonyms, actions, and extension-specific index configuration. Imported Products may exist and be active while search omits them or ranks them poorly because indexed fields, aliases, or message-queue processing are incomplete.
Early warning signs
| Early warning sign | What it indicates |
|---|---|
| Products are visible by direct URL but absent from search. | The Product record exists, but search indexing or configuration is incomplete. |
| Product numbers, EANs, or custom values are not searchable. | Required search fields are not included in the active search configuration. |
| Search synonyms and forwarding actions were not inventoried. | Merchandising behavior will not follow the source intent. |
| Index creation completes but aliases or queued processing remain incomplete. | The generated index is not yet the one serving storefront requests. |
Prevention
Preserve search keywords, Product visibility, searchable fields, properties, manufacturer data, synonyms, actions, and any Advanced Search configuration. Include index creation, message-queue processing, alias creation, and ongoing indexing ownership in the migration runbook.
Recommendation example
Use one Product found by name, one found by Product number, one dependent on a synonym, and one targeted by a search action. Trace them through the configured search fields and indexes.
Pass condition
Representative Products appear through the intended names, numbers, properties, manufacturers, and synonyms; search actions lead to valid destinations, and the required indexes and aliases remain current.
Cross-Pitfall Prevention Priorities
Shopware pitfall prevention depends on keeping Product data connected to sales channels, inherited variants, Rule Builder conditions, Shopping Experiences, language-aware custom fields, historical Order states, routes, search, and extension ownership. A correct Product row cannot compensate for a missing channel, rule, layout, or index relationship.
| Prevention layer | Required control |
|---|---|
| Sales-channel ownership | Connect Products, Customers, Categories, domains, languages, and visibility to the correct channel. |
| Inheritance control | Distinguish inherited parent values from variant-level overrides. |
| Rule dependencies | Preserve the data that Rule Builder conditions use for price, promotion, payment, and shipping behavior. |
| Experience assignment | Keep Shopping Experiences connected to the correct page type, entity, route, and sales channel. |
| Search delivery | Align searchable fields, synonyms, indexing, aliases, and queued processing. |
Conclusion
Shopware migrations fail when interconnected platform structures are flattened into isolated records. Sales channels define availability, properties generate variants, rules control commercial behavior, Shopping Experiences provide context, and extensions can own entire business domains.
The safest migration preserves each relationship and proves it through a platform-specific pass condition. When Products, channels, rules, content, Orders, URLs, search, and extensions agree, the migrated Store behaves as a coherent Shopware environment rather than a collection of imported entities.
Common Questions
Why can a Product exist in Shopware but remain unavailable to shoppers?
The Product can be inactive, hidden, excluded from the relevant sales channel, absent from the channel’s Category assortment, or missing the language, currency, domain, or visibility context required by that storefront.
Are Shopware properties always Product variants?
No. Properties can describe and filter Products without generating variants. Only selected property options used by the variant generator define sellable combinations.
Why must Rule Builder conditions be migrated separately from resulting prices or discounts?
The result is valid only under specific Customer, channel, currency, quantity, cart, time, or Order conditions. Copying the value without the rule applies it too broadly or not at all.
Can Shopping Experiences be migrated as ordinary CMS Pages?
Not reliably. Their page type, sections, blocks, elements, assignments, sales-channel context, links, and Product- or Category-specific overrides determine where and how the layout works.
How should Shopware custom fields be handled across languages?
Preserve the field definition and default-language value first, then retain intentional translated overrides. This keeps inheritance usable for templates, rules, and integrations.
Why can correct Shopware Products still be missing from search?
Search output depends on visibility, searchable fields, keywords, properties, synonyms, actions, index creation, queue processing, aliases, and extension configuration. Correct Product records alone do not guarantee indexed discovery.