How to plan a PIM migration without losing product data
Moving product information to a new PIM? Map fields, preserve relationships and validate channel output with a staged cutover and a usable rollback plan.
- Published
- Last updated
A safe PIM migration preserves product identity, maps the catalogue into the new structure and proves that downstream channels still receive the right information. You can move between product information management (PIM) systems when the source can export the required objects and the destination can store their meaning.
This procedure fits the person responsible for an existing catalogue and its replacement PIM. Supported fields can move through imports or an application programming interface (API), while unsupported workflows and channel rules need separate rebuilding. A successful import can still leave a variant with the wrong parent or an image pointing to the old system.
Define what moves and what stays
Define the migration boundary by object and business owner before choosing a transfer method. Inventory products, variants, attributes, translations, assets, product relationships, approvals and channel mappings. Record the source of each value, who can approve a change and which systems consume it.
Keep order transactions, payment records and customer accounts in their existing systems unless a separate project explicitly moves them. Recreate integration credentials through secure account setup. Give migration staff export access and restricted target import access, then remove temporary permissions after handover.
Write down which system owns updates at each stage. The old PIM remains authoritative during preparation and rehearsal. During a freeze, it remains the reference while editing pauses. After accepted cutover, the new PIM owns catalogue edits and outgoing feeds.
A replacement makes sense when the existing structure or publishing workflow prevents a required business change. Retain the current PIM when it already supports the work and the proposed move only relocates unresolved data problems. If nobody can explain what a field means, changing systems won’t settle it.
In-house work and migration services
Choose in-house PIM data migration when your team can own transformations and support the feeds after launch. PIM data migration services can provide that delivery capacity, but your catalogue owner must still approve meaning and omissions.
Use the same scope checklist for an internal team or supplier:
- Name the person who approves each source-to-target mapping and each excluded object.
- Assign cleanup of duplicates, invalid units, missing translations and outdated assets.
- Specify who builds transformations and who receives their source files and instructions.
- Require a rehearsal, rejected-record report and evidence from the destination’s channel output.
- Assign the freeze, final change capture, downstream switch and rollback decision.
- Define acceptance by reconciled records and working publishing, with an owner and response window for post-move exceptions.
A service agreement must identify unsupported objects and manual rebuild work. Include source-account retention, destination subscription dependencies and who receives failure notifications. Paying for a migration doesn’t make an unsupported approval history importable.
Map identifiers and structures
Map each source field to a target type, unit and allowed value while preserving a stable identifier. Keep a crosswalk between old and new internal IDs if the destination assigns its own. Preserve the identifier used by storefronts and feeds, including leading zeros.
Document parent-to-child links separately from product descriptions. A parent’s shared material might belong on a product model, while colour and size belong on variants. If the target uses a different hierarchy, record how inherited values become explicit values and how you will prevent them drifting later.
The Akeneo product resource specification illustrates why a flat row is incomplete: values carry locale and channel context, and metric values carry units. Its product model and media references also need their own handling.
For every unsupported field, choose a mapped replacement, a retained archive or an approved omission. Record what the target loses and who accepts that loss. Don’t hide an unknown attribute inside an unlabelled notes field and call it transferred.
Transfer matrix
Treat this matrix as a planning template. A method is usable only after a rehearsal proves that your source exporter and target importer support the object.
| Object | Supported method to establish | Retained fields | Lost without separate handling | Manual rebuild work |
|---|---|---|---|---|
| Products | Export and mapped import or API transfer | Stable ID and mapped values | Unsupported attributes | Approve replacements or archive |
| Variants and parents | Model import, then child references | Parent ID and variation axes | Inheritance meaning | Rebuild target hierarchy |
| Translations | Locale-aware values | Text and locale code | Unmapped locales | Enable locales and review fallback |
| Assets | Binary transfer and reference mapping | Original file and mapped metadata | Old URLs and transformations | Relink files and rebuild derivatives |
| Relationships | Reference import after both records exist | Relationship type and destination ID | Unsupported relation types | Recreate equivalent links |
| Approvals and publication rules | Separate supported configuration transfer | Explicitly supported settings | Untransferred history and rules | Rebuild permissions and channel jobs |
Worked mapping example
Use a small fixture before touching the full catalogue. This hypothetical source has parent COAT, child 00017-NV-S and child 00017-NV-M. Both children have colour code navy, mass 800 GRAM and an English description plus a French description.
The target mapping preserves both child identifiers as text and sets their parent to COAT. It maps navy to the existing option navy_blue, converts 800 GRAM to 0.800 KILOGRAM and keeps each description’s locale. One original image, coat-front.jpg, is shared by both children.
To execute the example in an isolated destination:
- Create the target family with size as the variation axis, the
navy_blueoption and the two required locales. - Import parent
COATthrough the target’s model importer. Confirm its shared fields before importing children. - Create a CSV file with the two child rows. Map the identifier as text, parent as a reference, colour as an option and mass as a decimal with a unit.
- Map the English and French description columns to their corresponding locales. Select the intended channel wherever the destination scopes descriptions by channel.
- Upload
coat-front.jpg, record its new asset reference and assign it to both children through the supported asset field. - Import the child rows, export them again and compare them with the mapped expectations in the next section.
These are mapping instructions, not universal CSV headers. Start from the destination’s exported sample so column names and separators match its importer. Akeneo’s import instructions document profile settings and parent ordering. They also warn that identifiers differing only by case refer to the same product.
If your source contains both Coat-A and coat-a, resolve that collision before an import into a case-insensitive destination. Preserve the original-to-replacement crosswalk wherever downstream systems still use the old identifiers.
Prepare a recoverable export
Keep an untouched, versioned source export and an asset manifest before transforming any records. Save schema definitions alongside data so future readers can distinguish an option code from a translated label.
Record product and parent counts separately. Count localised values by locale and channel, then count relationship links and asset assignments. Store rejected records with the source ID, error and responsible owner. Reconcile every source object to an imported object or an explicitly approved exception.
For the coat fixture, the expected result is one parent and two children. Each child retains two descriptions and one image assignment. The catalogue has one unique original image, two image assignments and no unresolved parent references.
For each asset, record its source ID, original filename, byte size and checksum alongside the products that use it. Compare checksums for byte-identical originals. Compare transformed derivatives through the documented transformation and visual inspection, because a resized image has different bytes.
Store a readable copy outside the migration pipeline and rehearse opening it with the retained schema and asset files. Keep the old account available through the agreed recovery window. A backup that depends on an expired login leaves you without a usable rollback source.
Rehearse with difficult records
Rehearse records that expose structure errors before importing routine products. Include a multi-level variant, missing optional values, multiple locales, linked assets and a relationship to another product. Add a disabled product and a deliberate invalid option to see how rejection handling works.
Import structure before dependent records. Establish controlled options, families and locales first, then parents and children, followed by relationships and asset assignments. Where a combined importer handles dependencies, keep the order its specification requires.
Compare the fixture against exact expectations:
- The destination contains
00017-NV-Sand00017-NV-M, each underCOAT, with leading zeros intact. - Both colour values resolve to
navy_blue, while the storefront shows the intended colour label. - Both mass values equal
0.800 KILOGRAM. A result of800 KILOGRAMfails acceptance. - English and French descriptions remain distinct and reach the intended channel.
- The current image loads for both children, without access to the old PIM.
- Repeating the supported update import changes existing children without creating duplicates.
Export from the target and compare identifiers and values by identifier, attribute, locale and channel. Equal totals alone can hide one missing record and one duplicate. Inspect the resulting storefront too: select both sizes, read their descriptions and compare their displayed attributes.
Record how blank values behave. Test whether an omitted field leaves its old value intact and whether an explicit empty value clears it. Keep an invalid row out of publication until its rejection is visible and resolved.
Cut over in stages
Cut over only after rehearsal passes and the people responsible for feeds can reverse their changes. Choose a complete editing freeze when final changes cannot be captured reliably. Use incremental extraction only when it accounts for every changed object, including deletions and linked assets.
Akeneo documents filters for product updates and linked-entity changes. These are distinct filter cases. A product-only timestamp query must not be treated as proof that every related change was captured.
Follow a single ordered cutover:
- Confirm the go/no-go owner, support contacts and rollback deadline. Pause outgoing jobs that could publish conflicting catalogues.
- Freeze source edits or record the agreed change-capture boundary. Keep the old PIM authoritative while the final export runs.
- Import final changes and reconcile additions, updates and removals. Prevent overlapping scheduled jobs from replaying older values.
- Compare the final destination export with the expected source snapshot plus accepted changes. Resolve blocking exceptions before switching feeds.
- Switch one downstream channel to the new PIM. Inspect its output and storefront, then switch the remaining channels in the agreed order.
- Declare the new PIM authoritative and reopen editing there. Send migration failure notifications to the named operators.
Set blocking conditions before the window opens. Missing sellable products, broken parent links, incorrect units and failed channel publication require a stop. Assign a decision for each lower-risk omission so nobody silently accepts it during the move.
If cutover fails, pause target publishing and edits, preserve the target’s latest export and restore the old channel configuration. Reconcile any changes made in the new PIM before resuming old-source updates. Otherwise rollback can overwrite legitimate edits made after the switch.
Confirm the new catalogue is authoritative
Confirm the replacement workflow by completing an ordinary catalogue change after cutover. Edit a description, update an asset and publish through the new PIM. Inspect the channel output and the storefront to confirm that the new values arrive without an old job overwriting them.
Compare final record totals and identifier sets, then check required fields, locale coverage, units and relationship targets. Open current assets and inspect shopper-facing comparisons between variants. Log each exception against its product ID, with an owner and resolution evidence.
Keep the old source read-only while exceptions and the recovery window remain open. Retire its schedules, credentials and paid account only after the replacement workflow passes and the retained archive is readable. Escalate unresolved import behaviour with the failing record, mapping version and job error, keeping credentials out of the support bundle.
Hand the new update rules to the people responsible for product data governance. They need to know who approves changes, which system owns each value and how publishing failures reach the right person.
Give your store its own shopping agent
Customers ask in their own words. Your agent finds, compares and checks out from your catalogue, right on your site.