What actually breaks during a product image migration
Product data migrates cleanly because it lives in structured fields. Images don't. They live in three places at once — the file in object storage, the URL that references it, and the metadata attached to it in the platform's database — and each moves independently during a replatform.
| Asset layer | Migrates automatically? | Typical outcome |
|---|---|---|
| Image files (binaries) | Usually yes | Re-uploaded to new CDN |
| Image URLs | No | New path structure, old URLs 404 |
| Alt text | Rarely | Dropped or replaced with file name |
| Image order / position | Sometimes | Reshuffled, wrong hero image |
| Variant-to-image mapping | Rarely | Color swatches point to wrong photo |
| IPTC / EXIF metadata | No | Stripped on re-encode |
| Transformation params | No | Wrong crops, wrong sizes |
Two of those rows do most of the damage. Variant-to-image mapping is a revenue bug — a shopper clicking "Navy" and seeing the black colorway converts worse and returns more. Image URLs are the SEO bug, and it compounds because image URLs are referenced from places you don't control: your Google Merchant Center feed, Meta and Pinterest catalogs, marketplace listings, affiliate content, press coverage, and email templates going back years.
Merchant Center and Meta catalogs cache image URLs. If your feed publishes new URLs while the old ones 404 before the new ones are crawled, listings can get disapproved for "image not accessible" and drop out of Shopping results entirely — usually within 48 hours of the cutover.
Step 1: Inventory before you export anything
You cannot map what you haven't counted. Before the migration begins, build a single source-of-truth spreadsheet or database table with one row per image, not one row per product. A 3,000-SKU catalog with an average of six images per product is 18,000 rows — that's the real scope of the job.
Each row needs at minimum:
- Full absolute image URL as it exists today, including any transformation query string
- Product SKU and handle/slug it belongs to
- Position in the gallery (1 = hero)
- Variant IDs the image is assigned to, if any
- Alt text exactly as stored
- Pixel dimensions and file size
- Format (JPEG, PNG, WebP, AVIF)
Pull this from the platform's API rather than the admin CSV export — most admin exports flatten galleries into a single comma-joined column and drop variant assignment entirely. Then cross-reference two external sources the platform doesn't know about: your Google Search Console Google Images performance report (export the top image URLs by impressions) and your current product feed file. Any image URL earning impressions is a URL that needs a redirect, even if the product itself is discontinued.
Sort your inventory by image impressions descending and draw a line at the 80th percentile of cumulative impressions. In most catalogs that's 10-15% of images. Those get manual QA after cutover; the rest get automated checks.
Step 2: Decide what migrates, what gets replaced, and what gets dropped
A replatform is the cheapest moment you will ever have to fix catalog image debt, because you are touching every asset anyway. Migrating 18,000 images one-for-one when 4,000 of them are low-resolution supplier photos from 2019 just carries the debt forward and inflates the migration itself.
Triage every image into one of three buckets:
Migrate as-is
- Meets the new platform's minimum resolution
- Matches current brand style guide
- Has earned search impressions
- Is referenced by an active ad or feed
Regenerate or replace
- Below 1600px on the longest edge
- Inconsistent background or color across the set
- Visible artifacts, dust, or old packaging
- Missing angles the new template expects
The third bucket — drop entirely — is for duplicates, images attached to products discontinued more than a year ago with zero impressions, and legacy sizes the new CDN will generate on the fly. Dropping these still requires a redirect decision, covered below, but it removes them from the upload and QA workload.
The "regenerate" bucket is where the economics changed. Rebuilding a few thousand off-standard images used to mean a re-shoot budget, and traditional retouching runs roughly $25-50 per image at agency rates — enough that most teams simply migrated the bad photos and lived with them. Tools like Retouchable make it practical to standardize backgrounds, correct color, and generate the missing angles across a full catalog during the migration window instead of deferring it indefinitely.
Step 3: Build the URL map and redirect plan
This is the step teams skip, and it is the one that determines whether image search traffic survives. You need a machine-readable map from every old image URL to its new counterpart, generated before cutover, not reconstructed afterward from server logs.
Generate it by joining on a stable key. Platform image IDs don't survive migration, and file names often get sanitized on re-upload, so the reliable key is SKU + gallery position. Your inventory already has both for the old catalog; capture the same two fields from the new platform after the import completes, then join.
| Scenario | Redirect action | Status |
|---|---|---|
| Image migrated one-for-one | Point old URL to new URL | 301 |
| Image regenerated, same slot | Point old URL to replacement | 301 |
| Image dropped, product still live | Point to product's hero image | 301 |
| Product discontinued, has impressions | Point to category or successor product image | 301 |
| Product discontinued, no impressions | Let it go | 410 |
Use 301, not 302 — a temporary redirect tells Google to keep the old URL indexed and never transfers signals to the new one. Use 410 rather than 404 for the deliberate drops; it tells crawlers the removal is intentional and gets the URL dropped from the index faster and more cleanly, which keeps your crawl budget focused on live assets.
If you are migrating off a platform you already migrated onto, you may have existing image redirects. Flatten them: old URL should point directly at the final new URL, never through an intermediate hop. Chains lose signal at each step and some crawlers stop following after a few.
Where you implement the map depends on your setup. If the old image host stays under your control (your own CDN or a subdomain), rules go at the edge — Cloudflare Workers, a CloudFront function, or an nginx map file. If the old images lived on the previous platform's CDN on a domain you don't own, you cannot redirect them at all. That's the hard case, and it's the reason to keep the old platform's plan active for 60-90 days after cutover while crawlers discover the new URLs from your updated sitemap and feed.
Step 4: Carry alt text, metadata, and structured data across
Alt text is the most commonly lost image asset in a replatform, and it is pure unforced error — the text exists in your inventory export, and every major platform's API accepts it on image upload. The reason it gets dropped is that bulk importers usually map product fields and ignore the nested image object.
Handle it as an explicit post-import pass: iterate your inventory, match on SKU plus position, and PATCH the alt text onto each new image record via the API. Budget for the fact that some images will have empty alt text in the old system too — the migration is a good moment to generate it, keeping it descriptive and specific ("navy merino crewneck sweater, front view on model") rather than keyword-stuffed.
Three more items in the same pass:
- IPTC and EXIF metadata. If you embed copyright, creator, or AI-disclosure fields, verify they survived the re-encode. Most CDN pipelines strip all metadata on transformation by default, which can quietly break AI-content labeling compliance you had in place.
- Product schema image arrays. Your JSON-LD
Product.imageproperty must list the new absolute URLs. Templates that hardcode a CDN hostname are a common miss. - Image sitemap. Regenerate it with the new URLs and submit it on cutover day. This is the fastest signal you can send about where the images moved.
Run the alt-text pass as a separate, idempotent script rather than folding it into the import. If the import needs to be re-run — and it usually does — you won't have to redo the metadata work, and you can re-run the pass safely to catch stragglers.
Step 5: Verify the migration actually worked
"The site looks fine" is not verification. The image layer fails in ways that are invisible on a spot check of ten product pages. Run these checks on a schedule for the first month.
Day 0, before DNS cutover: crawl the staging site and assert that every product has the expected image count, that no image returns a non-200, and that alt text is non-empty on the same percentage of images as the old site. Diff the old and new hero image for a random sample of 200 SKUs — if any hero changed, your position mapping is off.
Day 1: take your top 500 image URLs by impressions from the inventory and request each one. Every single one should return a 301 to a URL that itself returns 200. Then submit the image sitemap and push the updated product feed to Merchant Center and Meta.
Day 7 and Day 30: watch these four numbers.
Expect a dip in Google Images impressions in weeks one and two even with perfect redirects — reindexing takes time. What you are watching for is the shape of the recovery: a steady climb back toward baseline by week six is normal, and a flat line at the bottom means redirects are not being followed and you should re-check for chains, 302s, or a robots.txt rule blocking the new image path.
Also verify Largest Contentful Paint specifically. A new platform's default image transformation settings frequently serve larger files than your tuned old setup, and product page LCP regressions after replatforming are common enough to check for deliberately rather than assume.