WooCommerce 11.1 enables additional variation images in core, removes the feature toggle during the database update, and automatically deactivates the older additional variation images extension. The gallery uses _product_image_gallery on variation records and exposes gallery_image_ids through REST. A site can therefore look as if a plugin was unexpectedly disabled while the real risk is incomplete migration, stale caches, custom theme assumptions, or duplicate image metadata.
Use this for variable-product stores, large catalogs, custom product galleries, headless storefronts, importers, ERP sync, image CDNs, multilingual catalogs, staging clones, and sites that previously used the Woo variation images extension.
Quick answer
Before upgrading, inventory the extension, variation gallery metadata, attachment IDs, custom templates, import mappings, REST clients, and a sample of high-value products. Run the WooCommerce 11.1 database update on staging and confirm the old extension is deactivated only after core gallery support is active. Compare each sampled variation on desktop and mobile, inspect _product_image_gallery, read and write gallery_image_ids through REST, switch variations repeatedly, purge image and page caches, and prove rollback from the database snapshot.
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 |
|---|
| Extension installed | Database update complete | Extension inactive, core active |
| Multiple images | Variation gallery | Ordered IDs preserved |
| REST update | gallery_image_ids | Storefront changes once |
| Rollback | Database plus plugin | Previous gallery restored |
Diagnostic table
Use this table to connect the observed behavior to evidence and a verification step.
| Action | Evidence | Verification |
|---|
| Inventory extension and metadata | Record WooCommerce and extension versions, database version, update action ID, variation IDs, attachment IDs, theme overrides, gallery scripts, REST clients, importers, CDN, and cache layers. | Every sampled variation retains the intended ordered gallery without missing or duplicate images. |
| Run the staging database update | Sample variations with zero, one, many, deleted, duplicated, offloaded, translated, private, and shared gallery attachments before the database update. | REST gallery_image_ids reads and writes the same variation metadata used by the storefront. |
| Reconcile REST and storefront | After migration, compare extension activation, core feature state, _product_image_gallery values, REST gallery_image_ids, media-library records, product page markup, and selected-variation behavior. | Custom themes, mobile controls, direct URLs, CDN images, structured data, and social previews remain correct. |
| Repair theme or importer assumptions | Test classic and block themes, keyboard and touch navigation, rapid variation switching, direct variation URLs, lazy loading, image zoom, social previews, and structured product data. | The old extension stays inactive after verification and its data is not deleted until the rollback window closes. |
What to check first
- Record WooCommerce and extension versions, database version, update action ID, variation IDs, attachment IDs, theme overrides, gallery scripts, REST clients, importers, CDN, and cache layers.
- Sample variations with zero, one, many, deleted, duplicated, offloaded, translated, private, and shared gallery attachments before the database update.
- After migration, compare extension activation, core feature state, _product_image_gallery values, REST gallery_image_ids, media-library records, product page markup, and selected-variation behavior.
- Test classic and block themes, keyboard and touch navigation, rapid variation switching, direct variation URLs, lazy loading, image zoom, social previews, and structured product data.
- Rehearse rollback with the pre-update database and plugin package; do not reactivate both implementations on production as an untested emergency workaround.
Field notes
- Write the pass condition before changing anything and keep one repeatable synthetic fixture for the full test window.
- Record exact versions and UTC timestamps because deployments, caches, retries, scheduled actions, and background jobs can change the evidence.
- Test the public path and the stored server-side result, not only an admin preview, isolated command, or API response.
- Repeat verification after the relevant cache, queue, cron, webhook, and observation window has completed.
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 8125 _product_image_gallery
curl -sS --max-time 20 -u 'key:secret' 'https://example.com/wp-json/wc/v3/products/8124/variations/8125'
Why this usually happens
- The plugin deactivation is noticed before the required database update has finished.
- A custom theme checks the old extension class instead of core variation metadata.
- Image CDN or page cache retains a previous variation gallery response.
- An importer writes product gallery fields but not the variation-level field used by core.
Decision rule
Approve migration only when the extension deactivation matches a completed database update, variation image IDs reconcile, REST writes are stable, storefront switching works, caches are current, and rollback is tested.
Production verification checklist
- Every sampled variation retains the intended ordered gallery without missing or duplicate images.
- REST gallery_image_ids reads and writes the same variation metadata used by the storefront.
- Custom themes, mobile controls, direct URLs, CDN images, structured data, and social previews remain correct.
- The old extension stays inactive after verification and its data is not deleted until the rollback window closes.
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 extension and metadata
- Run the staging database update
- Reconcile REST and storefront
- Repair theme or importer assumptions
- Prove rollback before cleanup
Mistakes to avoid
- Changing production before recording exact versions, UTC timestamps, a stable fixture, the expected result, and a tested rollback point.
- Treating one successful screen as proof while stored records, logs, queues, caches, emails, APIs, and downstream systems remain unchecked.
- Testing only as an administrator instead of using the role, device, locale, cache state, payment state, and failure branch that customers reach.
- Leaving temporary exclusions, debug output, test accounts, broad permissions, or one-off repair code active after verification.
Questions teams ask during testing
Can I run this directly in production?
Begin with read-only evidence and use staging for package, database, checkout, form, permission, or security changes. If a production canary is necessary, make it identifiable, reversible, monitored, and unable to expose personal data or charge a customer.
How do I avoid a false positive?
Repeat the same fixture with the same versions, role, URL, locale, cache state, and integrations. Compare browser, stored, API, and log evidence instead of relying on one screen.
What should the evidence packet contain?
Keep UTC time, exact versions, synthetic record ID, expected result, actual result, relevant log lines, change made, rollback point, owner, and final verification. Redact secrets and personal data.
When is the test complete?
Close the work when the primary path passes, failure branches are understood, stored and downstream records reconcile, temporary changes are removed, and monitoring covers the next update.
What to tell the client or owner
Give the owner a concise packet with the affected workflow, exact versions, UTC test time, fixture ID, expected result, actual result, key logs, change made, rollback point, final result, unresolved risks, 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 test a WooCommerce gallery migration.
Related HandL WP guides
Use these related guides when the same issue touches tracking, security, checkout, or crawler visibility.
Verify API roundtrips and rollback choices
Use the WooCommerce 11.1 variation gallery REST and importer roundtrip test to preserve image IDs and ordering. If the upgrade is incomplete, follow the variation gallery rollback decision guide before reactivating the retired extension or restoring production.
Monitor the migration and stop legacy metadata drift
Large catalogs should track the 250-item variation gallery migration batches until no pending or failed action remains. Integration teams should also run the legacy gallery metadata drift audit to find importers or themes that still write the retired key.
Helpful references