PrestaShop migrations fail most often when records are present but their shop, language, combination, module, or commercial relationships have changed meaning. Prevention therefore has to follow the operational relationship behind each record rather than relying on record counts. The ten pitfalls below focus on recurring failure patterns that can leave a catalog apparently complete while buying, discovery, service, or integration behavior is weakened.
Pitfall 1: Flattening Combinations Into Ordinary Product Fields
What goes wrong
A source Product can arrive with its base record intact while the sellable variation structure is weakened. PrestaShop combinations carry the purchasing differences that distinguish one sellable choice from another, while features describe Products and customization fields collect buyer-provided values. Treating all three as interchangeable can create duplicate Products, missing variant prices, incorrect stock ownership, or a storefront that displays information without preserving the intended buying choice.
Early warning signs
The warning pattern is not a low Product count. It is a mismatch between what shoppers can select and what staff can manage. The highest-risk records are Products whose options change SKU, price, weight, image, availability, or stock.
| Signal | Likely meaning | Immediate concern |
|---|---|---|
| Every option became a feature | Descriptive and sellable structures were merged | The Product can display choices that cannot control the purchased item |
| Each combination became a separate Product | Parent–combination ownership was flattened | Categories, SEO, and merchandising may fragment |
| Stock exists only at the base Product | Combination-level inventory was not preserved | Sellable choices may oversell or appear unavailable |
Prevention
Classify every source option by business function before mapping it. A choice that changes the purchased SKU belongs in combination logic; a value used for comparison belongs in features; buyer-entered text or files belong in customization. Include representative Products with multiple option dimensions, price impacts, images, and stock behavior. Preserve stable external identifiers when an ERP or warehouse system recognizes the combination rather than only the parent Product.
Recommendation example
For a jacket sold by size and color, keep one Product with combinations for the sellable choices. Preserve the combination SKU, price effect, image relationship, and stock position. Keep “waterproof rating” as a feature and an optional embroidery message as customization rather than manufacturing separate Products for every value.
Pass condition
A buyer can select every required choice, the correct SKU and price are placed in the cart, combination stock changes independently where intended, and staff can trace each sellable choice to the same operational identifier used by connected systems.
Pitfall 2: Losing Multistore Ownership While Preserving the Records
What goes wrong
PrestaShop multistore can make one record visible, priced, translated, or configured differently across shops or shop groups. A migration that preserves the Product, Category, Customer, or CMS record but drops its shop context can expose the wrong catalog, merge regional content, or assign shared records to a shop where they were never intended to appear.
Early warning signs
The risk is highest when teams speak about “the PrestaShop store” as though it were one storefront. Differences in domain, language, currency, catalog, theme, pricing, or operational ownership indicate that shop context is part of the data meaning.
| Area | Multistore question | Failure if ignored |
|---|---|---|
| Products and Categories | Shared globally or assigned selectively? | The wrong shop can publish or hide the record |
| Prices and promotions | Shared or shop-specific? | Regional commercial logic can collapse |
| CMS and translations | Common content or localized per shop? | One market can overwrite another |
Prevention
Create a shop-ownership matrix for every in-scope record family. Distinguish truly shared data from values that vary by shop, language, or region. Use explicit shop identifiers rather than inferring ownership from a domain name or language. Where the Target Platform represents storefronts differently, define the destination relationship for each shop-specific value instead of copying only the common record.
Recommendation example
A merchant operates French and Belgian shops with a shared Product catalog but different descriptions, tax presentation, and promotions. Preserve the shared Product identity while assigning localized content and commercial values to the correct target storefronts rather than selecting one shop as the universal source.
Pass condition
Each target storefront exposes only its intended Products, Categories, content, language, and commercial context; shared records remain shared where appropriate; and no shop-specific value is silently promoted to a global default.
Pitfall 3: Migrating Customer Groups Without Their Commercial Meaning
What goes wrong
Customer groups can influence visibility, pricing, discounts, tax display, or access expectations. Copying group names without preserving the relationships they control creates accounts that look classified in the back office but receive ordinary storefront treatment. The problem is easy to miss when reviewers inspect Customer profiles but do not compare the buying result for each group.
Early warning signs
Group labels may exist while associated commercial outcomes disappear. The risk grows when source groups combine B2B, wholesale, employee, loyalty, tax, or regional logic.
| Warning sign | What it suggests | Business effect |
|---|---|---|
| Groups exist but all buyers see one price | Pricing relationship was not represented | Wholesale or negotiated expectations fail |
| Restricted Products are visible to everyone | Visibility ownership was lost | Private catalog controls disappear |
| Tax display is identical across groups | Group-linked tax context was flattened | Displayed and charged totals may diverge from policy |
Prevention
Document the outcome controlled by each source group, not only its name. Map the Customer-to-group relationship separately from the target configuration that makes the group meaningful. Consolidate duplicate or obsolete groups deliberately. Where multiple source groups are encoded in a single tag or custom field, define whether the target supports equivalent membership or needs a normalized hierarchy.
Recommendation example
For a wholesale group, preserve Customer membership and define the target owner for wholesale prices, restricted Products, and tax presentation. Do not approve the group because the word “Wholesale” appears on the Customer record.
Pass condition
Representative Customers enter the correct account context and receive the intended Product visibility, pricing, discount, and tax presentation associated with their group, with any intentional differences documented as target behavior.
Pitfall 4: Breaking Category Discovery While Retaining the Category Tree
What goes wrong
A Category import can reproduce names and parent relationships yet weaken how shoppers discover Products. PrestaShop navigation, layered filtering, feature use, merchandising, and theme behavior may depend on more than the tree itself. Empty Categories, Products assigned to the wrong default Category, or descriptive features that no longer support filtering can make a complete catalog difficult to browse.
Early warning signs
Category counts are usually healthy even when discovery is damaged. Warning signs appear in storefront paths, Product placement, filters, and default-Category behavior.
| Check | Failure pattern | Why it matters |
|---|---|---|
| Default Category | Product has several assignments but the wrong primary context | Breadcrumbs and canonical behavior can change |
| Feature coverage | Feature values exist only on part of a Product family | Layered navigation becomes inconsistent |
| Category depth | Deep branches were collapsed or duplicated | Shoppers lose expected browsing paths |
Prevention
Define discovery outcomes for representative Product families. Preserve all required Category assignments and identify the default Category where PrestaShop behavior depends on it. Normalize feature names and values before using them for filtering. Retire obsolete Categories only with an explicit redirect or merchandising destination rather than deleting them without route planning.
Recommendation example
For a footwear catalog, verify that one shoe remains in Men, Running, and Sale while retaining the intended default Category. Confirm that size, surface, and waterproof features are complete enough to support the target filtering experience.
Pass condition
Priority Product families can be reached through expected Category paths, breadcrumbs and default context are coherent, filtering uses complete normalized values, and retired branches lead shoppers to a purposeful destination.
Pitfall 5: Assuming Friendly URLs Preserve Route Identity Automatically
What goes wrong
Source URL keys, rewritten routes, language prefixes, and CMS paths do not automatically reproduce the same public address in a new PrestaShop environment. A record can be present while its high-value route changes, collides with another route, or resolves to the wrong shop or language. The resulting issue affects customers, campaigns, internal links, and search visibility.
Early warning signs
The strongest signals are duplicate rewritten values, unexplained language suffixes, missing shop context, or priority pages whose destination was never declared.
| Route type | Common migration gap | Required decision |
|---|---|---|
| Product or Category route | Old rewrite does not match target structure | Choose the canonical target and redirect source route |
| Multilingual route | Language-specific slugs collapse to one value | Preserve locale-specific destinations |
| CMS or campaign route | Page exists under a new path | Update internal links and redirect the historical route |
Prevention
Build a route ledger for priority Products, Categories, CMS pages, and campaign destinations. Include source URL, language, shop, intended target route, and redirect owner. Check uniqueness within the target routing context. Preserve meaningful slugs where feasible, but prefer one coherent canonical target over creating duplicate or competing routes.
Recommendation example
A French Product route and a Belgian Product route share a translated name but belong to different shops. Assign each to the correct shop-and-language destination and create redirects from both historical paths rather than keeping only the route with the most traffic.
Pass condition
Every priority historical route resolves directly or through a single purposeful redirect to the correct Product, Category, or CMS destination in the intended shop and language, without loops or collisions.
Pitfall 6: Treating Modules, Overrides, and Theme Logic as Migrated Data
What goes wrong
PrestaShop modules and overrides can create fields, alter checkout, add carriers or payment behavior, change Product presentation, or store integration identifiers. Themes can determine how catalog structures are rendered. Copying standard records does not reproduce this behavior, and copying module tables without understanding the consuming module can create unusable or unsafe data.
Early warning signs
The risk is visible when business-critical outcomes are described only by module names, when custom tables have no owner, or when the target theme expects different fields and hooks.
| Dependency | Question to answer | Likely owner |
|---|---|---|
| Module-created field | Which current process reads it? | Continuing module, integration, or restructured target field |
| Override or custom code | Which default behavior does it change? | Target implementation rather than record migration |
| Theme-specific content | Is the value data or presentation configuration? | Target theme/content setup |
Prevention
Inventory modules, overrides, custom tables, hooks, and theme dependencies by business outcome. Preserve a value only when a target consumer exists. Separate record migration from reinstalling, configuring, replacing, or rebuilding behavior. Avoid carrying dormant module data merely because it is present in the database.
Recommendation example
If a module stores a supplier reference used by an ERP export, preserve that reference in a target field or integration record that the continuing ERP process can read. Do not copy the module table if the module itself will not exist in the target environment.
Pass condition
Every business-critical module or override has a declared target owner, necessary data remains readable by that owner, and no storefront or operational process is assumed to continue solely because standard records were migrated.
Pitfall 7: Flattening Stock Ownership Across Combinations and Locations
What goes wrong
Inventory can appear correct at Product level while sellable combinations carry the wrong quantity or availability. External stock systems, advanced stock history, warehouse feeds, or shop-specific inventory can add further ownership layers. Flattening these values creates overselling, false out-of-stock states, or a target quantity that is immediately overwritten by a connected system.
Early warning signs
A single quantity per Product, missing combination identifiers, unexplained negative stock, or disagreement between the Store and an external system indicates an ownership problem rather than a simple import error.
| Inventory signal | Likely cause | Prevention focus |
|---|---|---|
| Parent total equals sum of all variants | Variant ownership was ignored | Preserve combination-level quantity or external stock key |
| Target quantity changes after sync | External system remains authoritative | Define opening balance and post-migration owner |
| One shop shows another shop’s stock | Shop context was flattened | Preserve shop/location relationship |
Prevention
Declare the authoritative inventory owner for each Product family and location. Preserve combination SKUs and external identifiers. Define whether migration supplies an opening balance, historical reference, or continuing inventory value. Exclude stale stock tables that no longer govern availability.
Recommendation example
For a Product with size combinations managed by a warehouse system, migrate the opening quantity by combination and preserve the warehouse SKU. Schedule the warehouse connection to become authoritative after cutover rather than treating the parent Product total as the permanent stock value.
Pass condition
The correct sellable combination is available in the correct shop or location, stock changes occur under the intended system owner, and reconciliation can connect every target quantity to a stable Product or combination identifier.
Pitfall 8: Preserving Historical Orders Without Their Explanatory Context
What goes wrong
An Order total and status are not enough to preserve what happened. Historical Orders may depend on Product combinations, Customer groups, taxes, carriers, discounts, refunds, messages, and state history. If these relationships are flattened, staff can see a transaction but cannot explain the amount, identify the purchased variation, or understand what fulfillment or refund action occurred.
Early warning signs
Orders look complete at list level but become ambiguous when opened. Missing line-level option detail, generic statuses, absent discount context, or detached Customer records are typical signals.
| Order context | Failure if absent | Service consequence |
|---|---|---|
| Combination or customization detail | Purchased item cannot be identified | Returns and support decisions become unreliable |
| State history and messages | Operational sequence is lost | Staff cannot explain fulfillment or cancellation |
| Discount, tax, and shipping lines | Total cannot be reconciled | Finance and customer service lose confidence |
Prevention
Preserve line-level Product identity and descriptive purchase context even when the target cannot recreate every legacy workflow state. Map statuses by meaning rather than label similarity. Keep financial lines distinguishable. Preserve source Order numbers and external references when other systems use them for lookup.
Recommendation example
For a refunded Order containing a size-and-color combination and a voucher, retain the purchased combination description, original amounts, discount line, refund context, Customer association, and source reference rather than representing it as one generic completed Order.
Pass condition
Staff can identify what the Customer bought, how the total was formed, which state sequence occurred, and what refund or fulfillment context remains relevant, without consulting the retired source Store for ordinary support questions.
Pitfall 9: Carrying Inconsistent Localization Into a Shared Catalog
What goes wrong
Multilingual content often contains partial translations, duplicated slugs, fallback text, HTML differences, and module-created fields that are translated inconsistently. Migrating every value exactly as stored can expose source-language content in the wrong shop or produce empty storefront sections where the target expects a locale-specific value.
Early warning signs
Products have a translated name but not a description, category slugs collide across locales, or one shop uses copied content that should remain distinct.
| Localization issue | Visible result | Control |
|---|---|---|
| Missing locale value | Blank or fallback storefront content | Define approved fallback or completion rule |
| Same slug in conflicting contexts | Route collision or wrong destination | Assign locale/shop-aware routes |
| Embedded source-domain links | Customers return to the old Store | Rewrite links to target destinations |
Prevention
Audit translation completeness by high-value record family and locale. Normalize encoding and HTML. Decide where fallback is acceptable and where missing content must remain unpublished until completed. Treat links, media references, and SEO fields as localized relationships rather than plain text.
Recommendation example
A Product has complete French content and only an English name. Publish the French version normally, apply the approved English fallback policy, and prevent an incomplete English description from inheriting a French source-domain link.
Pass condition
Each published locale shows the intended language, routes and media resolve within the correct shop context, and missing translations follow a deliberate fallback or publication rule rather than accidental inheritance.
Pitfall 10: Preserving External Identifiers Without Preserving Their Consumers
What goes wrong
Source databases often contain ERP IDs, supplier keys, marketplace IDs, legacy Product references, and module-specific lookup values. Copying them into an arbitrary note field preserves characters but not function. Omitting them can break reconciliation, while duplicating them can cause connected systems to update the wrong record.
Early warning signs
Teams can list identifiers but cannot state which system owns them, whether they must be unique, or how they are queried after migration.
| Identifier | Consumer question | Target requirement |
|---|---|---|
| ERP Product or combination ID | Which sync job uses it? | Stable unique field exposed to the integration |
| Marketplace listing ID | Does the listing remain active? | Continuing channel relationship or deliberate retirement |
| Legacy Order reference | Who searches by it? | Visible searchable historical reference |
Prevention
Create an identifier contract: source field, record owner, target location, uniqueness rule, format, and consuming system. Preserve only active or evidential identifiers. Keep parent Product and combination keys distinct. Test lookup and update behavior through the continuing integration or operational workflow.
Recommendation example
If an ERP updates stock by combination reference, place that reference on the target sellable combination or integration record. Do not store it only on the parent Product or in an admin note that the sync process cannot query.
Pass condition
Every required external identifier is unique where expected, retrievable by its continuing consumer, attached to the correct record level, and demonstrably supports reconciliation or integration behavior.
Cross-Pitfall Prevention Priorities
The recurring PrestaShop risks can be controlled through three connected review tracks.
| Prevention priority | What it protects | Evidence before approval |
|---|---|---|
| Preserve combination and stock meaning | Combinations, attributes, locations, and sellable inventory | Representative Products retain the correct choices, identifiers, stock ownership, and availability. |
| Preserve multistore and commercial context | Shop ownership, Customer groups, localization, Categories, and pricing | Records appear in the correct shop, language, currency, group, and browse context. |
| Separate modules and integrations from migrated records | Overrides, themes, external identifiers, and operational consumers | Every non-core dependency has a target owner, implementation decision, and validation method. |
Conclusion
A reliable PrestaShop outcome is built from explicit relationships: Products to combinations, Categories to discovery, Customers to groups, records to shops and languages, and custom values to continuing modules or integrations. When those relationships are defined and tested through representative business scenarios, the migration can preserve how the Store operates rather than only what its database contains.
Common Questions
Why are PrestaShop combinations a major migration risk?
Combinations can own SKU, price, image, weight, and stock differences. Flattening them into features or separate Products changes the sellable structure and can affect cart and inventory behavior.
Does multistore require separate copies of every record?
Not necessarily. Some data may be shared while other values are shop-specific. The migration should preserve the intended ownership rather than duplicating everything or treating one shop as universal.
Should every module table be migrated?
No. A module record should be preserved only when a continuing target component or operational process needs it. Dormant or orphaned module data should not be copied for completeness.
How should Customer groups be evaluated?
Evaluate the commercial outcome connected to each group, such as pricing, visibility, tax display, or access, not merely whether the group label exists.
What is the safest way to preserve PrestaShop URLs?
Use a route ledger that records source path, shop, language, target destination, and redirect owner for priority Products, Categories, CMS pages, and campaigns.
What proves that external identifiers were preserved correctly?
The continuing ERP, warehouse, marketplace, or support workflow can locate and update the intended target record using the preserved identifier at the correct Product, combination, Customer, or Order level.