Research library

Sources checked: October 9, 2026

Product Information Management (PIM) Migration and Catalog Cutover Runbook

A catalog migration is not just a file conversion. It changes how products are identified, described, approved, published, and consumed by storefronts and operational systems. The safest path is a sequence of reversible, measured transitions in which field ownership and acceptance criteria are explicit before the first production write.

This runbook is vendor-neutral. Platform-specific notes below illustrate why import behavior must be tested against the exact target and current documentation; they are not a universal migration method.

1. Define the migration boundary and decision owners

Start with the business outcome and a bounded scope: brands, catalogs, locales, product types, variants, channel projections, images and documents, inventory or price fields, and downstream consumers. List exclusions too. Product descriptive data, sellable identity, inventory, pricing, assortment eligibility, and publication status may be owned by different systems; moving them in one undifferentiated batch obscures risk.

Inventory the source and destination systems, interfaces, scheduled jobs, caches, search indexes, marketplaces, feeds, portals, ERP/PIM workflows, and manual spreadsheets that read or write the affected data. For each field or domain, document the current writer, intended future writer, consumers, refresh timing, and fallback if its source is unavailable. Choose a transition owner, data steward, integration owner, channel or merchandising approver, quality lead, and rollback authority. One person may hold several roles, but approval and pause authority should be named rather than assumed.

Agree the operating constraints before building the migration: target launch window, blackout periods, acceptable stale-data interval, maximum tolerated missing or rejected records, customer-visible risk, support coverage, and who can call a no-go. Give each gate a measurable threshold and an evidence location.

2. Build the field map and identity crosswalk

Create a versioned mapping specification before writing transformation code. For every source field, record its meaning, source path, target path, target type and cardinality, transformation, null/blank behavior, default policy, owner, sensitivity, validation rule, and downstream use. Classify each field as authoritative, derived, destination-specific, deprecated, or out of scope. Never silently repurpose a field just because the new system has a similarly named column.

Keep business identity separate from system identity. Establish a stable internal product key and, where separately sellable items exist, a stable variant or item key. Preserve source IDs and destination IDs in a crosswalk with effective dates and status. Track SKU, GTIN or other industry identifiers, URL handle, product-family key, variant key, and platform-generated IDs as distinct identifiers with explicit uniqueness and lifecycle rules. Define how duplicates, merged products, split variants, retired identifiers, and future reactivation are resolved. Referential checks should prove that each child variant, category, media asset, and related record points to the intended parent.

Mapping elementExample decision to record
Stable master keyitem-00482; immutable across a title or SKU correction.
Source/destination IDsStore both IDs and their mapping status; do not substitute one platform's ID for the business key.
Sellable identityDefine whether each SKU is a distinct orderable variant, pack, or unit-of-measure representation.
Field transformationConvert source unit and value into the target unit under an approved conversion rule.
Ownership and validationName the approving steward and the rule that blocks publication when invalid.

Shopify's CSV guidance illustrates why target identity and update semantics deserve a dry run: its import workflow can match products by handles, and changing or omitting related variant option columns can affect variant records. commercetools documents import resources identified by keys and references to other resources by keys. These are product-specific behaviors, not portable assumptions; test the exact import mode and target version before choosing keys or update semantics. Shopify CSV import guidance · commercetools Import Resources.

3. Normalize without erasing meaning

Write deterministic transformations for units, precision, currencies where in scope, enumerated values, whitespace, punctuation, encoding, date/time and locale formats, category mappings, and controlled terms. Preserve original source values in an auditable landing layer or migration snapshot so a transformed value can be traced and corrected. Keep display labels separate from stable machine keys. Distinguish unknown, not applicable, intentionally blank, and missing; do not turn each into an arbitrary default. Maintain locale-specific copy as locale-specific content rather than allowing one locale's cleanup to overwrite another.

Specify transformations as tested rules, not undocumented spreadsheet edits. Record mapping version, migration batch, source extract timestamp, transformation version, and target result for each run. Make reruns idempotent where possible: repeating a batch should update the intended record rather than create duplicates. Protect against a change in an upstream source during transformation by preserving a snapshot or a reproducible extract reference.

4. Profile quality and assign ownership

Profile the complete in-scope source set before migration and classify defects by severity, affected channel, and owner. At minimum, check:

  • Identity: duplicate business keys, duplicate identifiers, missing keys, invalid SKU/GTIN format where required, and unresolved source-to-target crosswalks.
  • Relationships: orphaned variants, broken category or parent links, missing references, duplicate media links, and invalid family structures.
  • Shape and meaning: wrong data type, invalid cardinality, unsupported enumeration, unit mismatch, invalid locale, accidental whitespace, and ambiguous nulls.
  • Completeness and consistency: required-field coverage by product type and destination, conflicting product/variant values, stale content, and inconsistent duplicate records.
  • Publication readiness: channel eligibility, required content and assets, visibility state, and any dependent search or feed input.

Assign a named steward to each field family and a remediation owner to each defect class. Track exceptions in a queue with record key, failing rule, severity, owner, due date, disposition, and approval. A completeness percentage is not a launch decision by itself: a small number of missing values can affect a critical product, while many optional blanks may be acceptable. Agree hard blockers, allowable exceptions, and escalation authority with channel and operations owners before the first parallel load.

5. Run parallel loads and validate against a baseline

Capture a timestamped baseline before changing production behavior. Include total products and variants by type/status, distinct identifier counts, relationship counts, required-field coverage, channel-eligible counts, and sampled field values. Where practical, retain deterministic checksums or canonicalized record comparisons. Exclude expected system-generated fields from equality comparisons but name those exclusions.

Run a representative pilot in a non-production destination or safely isolated unpublished state. Include edge cases—not just easy records: multiple variants, duplicate candidates, localized values, empty-but-intentional fields, discontinued items, images, categories, references, and records with known exceptions. Validate the transformed output, import results, target records, and rendered experiences. Use a separate identity check and a field-level comparison so a matching record count cannot hide mismapped content.

Then perform a full parallel load or shadow comparison while the existing catalog remains authoritative. Reconcile counts by product type, status, locale, and channel; compare business keys and crosswalks; sample and compare critical fields; verify relationships and media; inspect rejected and silently skipped rows; and test key journeys such as search, product detail, variant selection, buyer-specific assortment, and downstream export. Repeat after applying a controlled delta to prove that changes made during the parallel period are not lost. Log each discrepancy with severity, owner, resolution, retest evidence, and accepted exception approval.

Platform-specific import behavior makes destructive testing important. Shopify states that an import started by CSV cannot be canceled and explains overwrite behavior for matching handles, including how blank and omitted columns can have different effects. commercetools' import documentation describes staged and current product representations and import-resource update behavior. Validate those semantics in a representative test before production; never treat “import completed” as proof of correct customer-visible data. Shopify import behavior · commercetools catalog lifecycle.

6. Sequence cutover as controlled state changes

Write the sequence and owner for every action in the change plan. A common order is:

  1. Readiness gate: approve mappings, defect thresholds, snapshots, access, monitoring, support coverage, communications, and rollback rehearsals. Confirm all critical records and references pass.
  2. Write coordination: pause or queue edits to affected fields, or define a reliable delta-capture process. State which source remains authoritative during the freeze and how last-minute changes are replayed.
  3. Final delta: capture changes since the baseline, transform with the approved mapping version, load the final delta, and reconcile it independently. Do not advance on unexplained rejects or duplicate creation.
  4. Visibility switch: change the smallest possible publication, integration, or read-routing control. Keep the old path intact but prevent dual writers. If customer-visible publication is separate from import, verify a controlled sample before broad release.
  5. Smoke test: check representative product pages and variants, search and filters, channel eligibility, identifiers exposed to dependent systems, assets, and critical exports. Have named business and technical approvers record the decision.
  6. Stabilization: maintain enhanced monitoring and a change freeze for the agreed period. Resume ordinary edits only after the new writer and downstream consumers have been confirmed.

Where the platform supports unpublished or staged content, use that capability only after confirming exactly what remains visible. commercetools describes staged product data separately from the current customer-facing representation until publication; this illustrates a useful separation, but the exact publication model is platform-specific. Product catalog overview.

7. Pre-agree rollback criteria and recovery steps

Define no-go and rollback thresholds before the maintenance window. Example triggers include a broken or ambiguous identity crosswalk, duplicate creation above the approved threshold, missing or corrupted critical attributes, widespread variant/relationship loss, incorrect channel visibility, failure of a critical downstream feed, unacceptable page/search errors, or reconciliation outside the agreed tolerance. Set numeric limits based on business impact and baseline—not a universal percentage.

Specify who can pause writes, who can restore the old read path, which snapshot or previous publication state is valid, how deltas accumulated during the migration will be retained, and how operators verify restoration. Separate “stop further batches” from “restore customer visibility”; they may require different controls. Do not roll back by blindly re-importing an old full export if it could overwrite legitimate intervening edits or delete fields through target-specific update semantics. Preserve audit evidence, then reconcile and replay approved changes after recovery. Test the rollback or forward-fix choice in advance, including the fact that external channels and caches may lag.

Choose forward repair instead of rollback only when the defect is bounded, customer impact is understood, the correction is tested, and named owners approve continued cutover. Record the decision, affected keys, mitigation, and deadline. If criteria are exceeded or evidence is unclear, stop and escalate rather than improvising.

8. Reconcile after the switch and monitor the new master

Run an immediate reconciliation after the visibility switch, again after the first normal edit/sync cycle, and at a cadence through the stabilization period. Compare source, target, and destination projections on:

  • Record and distinct-identifier counts by type, status, locale, and channel.
  • Missing, duplicate, orphaned, rejected, or unexpectedly retired keys.
  • Critical attributes, product/variant relationships, assets, and publication/eligibility state.
  • Integration lag, failed or retried messages, export/feed rejects, and search-index freshness.
  • Buyer-facing behavior, support reports, and any accepted migration exceptions.

Monitor both data and process: time since last successful update, queue depth, failure rate by mapping version, exception age and ownership, unauthorized edits, field drift, and whether the declared system of record is actually the only active writer. Alert on actionable thresholds and route each alert to a named owner with a runbook response. Keep a record of reconciliation results and unresolved exceptions; retire the old feed, credentials, and manual workarounds only after dependencies are confirmed and an approved retention plan is in place.

For connected operating concerns, continue with the ERP integration architecture guide, OMS architecture guide, inbound ASN/DESADV guide, or catalog SEO migration guide.

First-party source register

Sources checked on October 9, 2026. Vendor documentation is cited only for the specific behaviors described above; follow the current documentation for the exact product, API version, import mode, and account configuration before implementation.

Education-only note

This guide is educational technical research for B2B commerce teams. It does not provide legal, tax, accounting, financial, security, compliance, or individualized implementation advice. Verify current vendor documentation, destination requirements, and your own operating constraints before making a decision.

Continue reading