WooCommerce 11.1 keeps existing _wc_additional_variation_images metadata for compatibility but core edits are not written back to that key. An importer, extension, theme, or custom job that still writes the legacy value can create a split state: wp-admin and core APIs show one gallery while another integration reads or rewrites the old gallery.
Use this for stores migrating from WooCommerce Additional Variation Images, custom importers, ERP or PIM sync, multilingual plugins, headless storefronts, and themes that read variation postmeta directly.
Quick answer
Treat _product_image_gallery on the variation and the WooCommerce product APIs as the current source of truth. Build a sample of migrated variations and record both metadata keys, REST gallery_image_ids, admin editor values, storefront order, translation relationships, and last writer. Make one edit through each real system and observe which fields change. Stop any integration that writes only _wc_additional_variation_images, map it to the supported getter, setter, or REST property, and keep the old value read-only until rollback policy allows cleanup.
Test scenarios to run
Run the same controlled fixture across these branches. Write down the expected result before testing so a surprising response is easy to identify.
| Scenario | Fixture | Expected result |
|---|
| Admin edit | Core gallery | Legacy remains historical |
| REST edit | gallery_image_ids | Storefront follows core |
| Old importer | Legacy key only | Drift detected |
| Translation | Mapped attachments | Locale galleries correct |
Diagnostic table
Use this table to connect the observed behavior to evidence and a verification step.
| Action | Evidence | Verification |
|---|
| Inventory both metadata keys | Inventory code, SQL, import maps, webhooks, APIs, themes, extensions, and scheduled jobs that read or write _wc_additional_variation_images or _product_image_gallery. | Every active integration reads and writes the supported core gallery contract. |
| Choose the supported source of truth | Export a marked sample with variation ID, parent, language, featured image, core gallery IDs, legacy gallery IDs, REST output, storefront order, edit source, and modified time. | Legacy metadata cannot overwrite a newer core edit through a scheduled or manual path. |
| Trace every writer | Edit the same fixture through wp-admin, wc/v3 REST, CSV import, ERP or PIM, translation workflow, bulk editor, and any custom gallery interface. | Admin, REST, CSV, translated products, and storefront output agree on attachment IDs and order. |
| Update importers and themes | Trace update_post_meta calls, API requests, importer logs, cron jobs, webhooks, cache invalidation, and storefront responses to identify the last writer after every edit. | A dated export preserves the pre-cleanup values and last-writer evidence. |
What to check first
- Inventory code, SQL, import maps, webhooks, APIs, themes, extensions, and scheduled jobs that read or write _wc_additional_variation_images or _product_image_gallery.
- Export a marked sample with variation ID, parent, language, featured image, core gallery IDs, legacy gallery IDs, REST output, storefront order, edit source, and modified time.
- Edit the same fixture through wp-admin, wc/v3 REST, CSV import, ERP or PIM, translation workflow, bulk editor, and any custom gallery interface.
- Trace update_post_meta calls, API requests, importer logs, cron jobs, webhooks, cache invalidation, and storefront responses to identify the last writer after every edit.
- Disable legacy writes on staging, repeat round trips, and retain a rollback export before cleaning or transforming preserved metadata.
Field notes
- Write the pass condition before changing anything. A repeatable synthetic fixture makes the before and after comparison useful.
- Keep exact versions and UTC timestamps because scheduled jobs, caches, retries, and background processing can change the evidence.
- Check the public experience and the stored server-side result. Admin previews and isolated API calls do not prove the whole workflow.
- Repeat the test after the relevant cache, queue, scheduled action, webhook, and observation window has finished.
Useful command or data shape
Adapt paths, IDs, and privacy handling to the site before running commands or storing data on production.
wp post meta get VARIATION_ID _product_image_gallery
wp post meta get VARIATION_ID _wc_additional_variation_images
wp wc product_variation get VARIATION_ID --user=ADMIN_ID
# Compare IDs and order after each named writer runs.
Why this usually happens
- An integration uses direct postmeta because it predates the core variation gallery API.
- Preserved legacy values look authoritative after migration even though they are no longer synchronized.
- A scheduled import overwrites a recent admin edit using stale gallery IDs.
- A theme reads a different key from the admin editor and API.
Decision rule
Complete the migration only when supported APIs and core metadata own every current write, legacy data is read-only or unused, and admin, REST, import, translations, and storefront show the same ordered IDs.
Production verification checklist
- Every active integration reads and writes the supported core gallery contract.
- Legacy metadata cannot overwrite a newer core edit through a scheduled or manual path.
- Admin, REST, CSV, translated products, and storefront output agree on attachment IDs and order.
- A dated export preserves the pre-cleanup values and last-writer evidence.
Safe fix order
Use a sequence that makes each result easy to prove. Stop when new evidence changes the scope or owner of the problem.
- Inventory both metadata keys
- Choose the supported source of truth
- Trace every writer
- Update importers and themes
- Retain a rollback export before cleanup
Mistakes to avoid
- Changing production before recording exact versions, UTC time, the affected fixture, current behavior, and a tested rollback point.
- Accepting one successful admin screen while the public page, stored record, API response, accessibility tree, queue, email, or downstream system remains unchecked.
- Testing only as an administrator instead of the role, browser, device, locale, network state, and failure path that a real customer reaches.
- Leaving broad credentials, debug logs, temporary filters, synthetic records, or recovery code active after verification.
Questions teams ask during testing
Should I test this on production?
Use production for read-only evidence first. Reproduce the change on staging with a current data shape, theme, extensions, cache, and browser mix. If a production canary is necessary, make it reversible, identifiable, monitored, and unable to charge a customer or expose personal data.
How do I rule out a cache artifact?
Record the origin response, purge only affected paths, and repeat in private and normal sessions. Compare stored data and server logs with the visible page. A cache hit is useful evidence only when you know which version it contains.
What belongs in the evidence packet?
Keep UTC time, exact versions, fixture ID, role, browser, expected result, actual result, relevant response or log lines, change made, rollback point, owner, and final verification. Redact passwords, tokens, personal data, and private URLs.
When is the test complete?
Close it when the main path and important failure branches pass, records reconcile across systems, accessibility and mobile checks are complete, temporary changes are removed, and monitoring covers the next update or business cycle.
What to tell the client or owner
Give the owner a short packet with the affected workflow, exact versions, UTC test time, fixture ID, expected result, actual result, key evidence, change made, rollback point, unresolved risk, owner, and next review date. Remove credentials and personal data before sharing it.
When HandL WP should help
Bring in help when this affects leads, checkout, search visibility, security, paid media reporting, or a client production site. HandL WP can trace the issue through WordPress, hosting, cache, tracking, and Search Console, then verify the workflow after the technical fix.
If this is active on a production site, have HandL WP audit WooCommerce product data.
Related HandL WP guides
Use these related guides when the same issue touches tracking, security, checkout, or crawler visibility.
Helpful references