WooCommerce 11.1 brings variation galleries into core and exposes attachment IDs through the readable and writable gallery_image_ids property on the wc/v3 variation REST API. The variation featured image remains separate. Integrations that merge both fields, write legacy metadata, reorder IDs, or import remote images without stable mapping can show the wrong product media.
Use this for ERP and PIM syncs, CSV importers, marketplace tools, headless storefronts, product feeds, migration scripts, multilingual catalogs, custom themes, and stores with different galleries for each variation.
Quick answer
Create a variable product with a parent featured image, parent gallery, and four variations: its own ordered gallery, one featured image only, an empty gallery, and intentionally reordered images. Read every variation through wc/v3, write the same gallery_image_ids back, export and reimport, run the 11.1 database migration, and read again. Attachment IDs, order, empty values, featured images, alt text, storefront switching, and headless output must match the fixture without falling back to stale legacy metadata.
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 |
|---|
| Read | Three ordered IDs | Same order returned |
| Write | New ID sequence | Core meta updates |
| Omit property | Change price only | Gallery unchanged |
| Clear | Empty array | Variation fallback documented |
Diagnostic table
Use this table to connect the observed behavior to evidence and a verification step.
| Action | Evidence | Verification |
|---|
| Freeze attachment ID fixtures | Record WooCommerce and WordPress versions, database update state, product and variation IDs, attachment IDs, featured image, gallery order, legacy metadata, importer, theme, and cache layers. | REST reads and writes preserve the exact ordered gallery_image_ids fixture. |
| Read and write through wc/v3 | Build variation fixtures for ordered gallery IDs, duplicate IDs, invalid ID, inaccessible image, deleted attachment, empty array, omitted property, and a featured image that also appears in the gallery. | Omitting the property leaves the gallery unchanged while an intentional empty array follows the documented clear behavior. |
| Run importer roundtrips | Run REST GET, REST PUT, partial update without gallery_image_ids, CSV export, CSV import, staging migration, Action Scheduler completion, and a second REST read. | CSV and migration jobs retain media identity and complete without repeatedly processing the same variation. |
| Finish scheduled migration | Compare admin media, _product_image_gallery, WC_Product_Variation getters, REST output, storefront selection, thumbnails, zoom, lightbox, headless response, and cache after purge. | Every storefront switches variations without stale thumbnails, duplicate featured images, broken media, or wrong alt text. |
What to check first
- Record WooCommerce and WordPress versions, database update state, product and variation IDs, attachment IDs, featured image, gallery order, legacy metadata, importer, theme, and cache layers.
- Build variation fixtures for ordered gallery IDs, duplicate IDs, invalid ID, inaccessible image, deleted attachment, empty array, omitted property, and a featured image that also appears in the gallery.
- Run REST GET, REST PUT, partial update without gallery_image_ids, CSV export, CSV import, staging migration, Action Scheduler completion, and a second REST read.
- Compare admin media, _product_image_gallery, WC_Product_Variation getters, REST output, storefront selection, thumbnails, zoom, lightbox, headless response, and cache after purge.
- Confirm API credentials have the narrowest product permissions and logs do not contain consumer secrets, authorization headers, private media URLs, or customer data.
Field notes
- Write the pass condition before changing anything. A repeatable synthetic fixture makes the before and after comparison far more useful.
- Keep exact versions and UTC timestamps because scheduled jobs, caches, OAuth refreshes, 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.
curl -sS --max-time 20 -u 'key:secret' \
'https://example.com/wp-json/wc/v3/products/810/variations/812'
# Compare image.id separately from gallery_image_ids, then repeat after import and migration.
Why this usually happens
- An integration combines the variation image property with gallery_image_ids and duplicates the featured image.
- A legacy importer writes _wc_additional_variation_images after core has become the source of truth.
- A partial REST update sends an empty array instead of omitting an unchanged property.
- A CDN or product object cache serves media from before the migration completed.
Decision rule
Approve the integration when gallery IDs, order, featured-image separation, empty-state behavior, and media rendering remain identical across REST, importer, migration, admin, theme, and headless paths.
Production verification checklist
- REST reads and writes preserve the exact ordered gallery_image_ids fixture.
- Omitting the property leaves the gallery unchanged while an intentional empty array follows the documented clear behavior.
- CSV and migration jobs retain media identity and complete without repeatedly processing the same variation.
- Every storefront switches variations without stale thumbnails, duplicate featured images, broken media, or wrong alt text.
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.
- Freeze attachment ID fixtures
- Read and write through wc/v3
- Run importer roundtrips
- Finish scheduled migration
- Purge and verify storefronts
Mistakes to avoid
- Changing production before recording plugin versions, WordPress version, PHP version, UTC time, the exact fixture, and a tested rollback point.
- Accepting one successful admin screen while the public form, stored record, API response, accessibility tree, cache, 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 test accounts, broad credentials, debug logs, temporary compatibility filters, or synthetic customer data 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, caching stack, 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 know the result is not a cache artifact?
Record the origin response, purge only the affected paths, and repeat the test in a private session and a normal session. 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 can I close the test?
Close it when the primary 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 test WooCommerce variation galleries.
Related HandL WP guides
Use these related guides when the same issue touches tracking, security, checkout, or crawler visibility.
Protect categories during the next CSV reupload
When a catalog update changes more than gallery data, run the WooCommerce 11.1 CSV reupload category preservation test. It checks nested terms, attributes, images, variation identity, omitted columns, empty cells, and second-import idempotency.
Helpful references