Assets & tasks / MERCHANT WORKFLOW
Why Doesn't Changing a BigCommerce Product Thumbnail Update the Selected Variant Image?
Because BigCommerce stores product-thumbnail and variant-image relationships separately. The product image resource uses an <code>is_thumbnail</code> flag for the image displayed on product listing pages, while a separate variant-image endpoint controls the image associated with a selected variant. Updating one relationship does not establish that the other changed.
Identify the image role before editing
BigCommerce's Catalog Overview documents product images at /v3/catalog/products/{product_id}/images. Setting is_thumbnail to true selects the thumbnail used on product listing pages. BigCommerce states that a product can have only one thumbnail image at a time.
Its separate variant-image endpoint targets /v3/catalog/products/{product_id}/variants/{variant_id}/image and permits one explicitly associated image per variant.
These are two independent decisions: which image represents the product in a listing context, and which image is associated with a selected SKU.
| Visible symptom | First record to inspect |
|---|---|
| Wrong product listing thumbnail | Product image and is_thumbnail |
| Wrong image after variant selection | Variant-image association |
| Unexpected gallery order | Product image collection and storefront |
The actual storefront theme may present these resources differently. The API documentation does not establish identical switching behavior for every custom theme.
Use one change for the affected relationship
Start with the product ID and exact variant ID. Read the current product images, their thumbnail flag and order, and the relevant variant's assigned image.
If the product listing card is wrong, investigate the product-level thumbnail. If the selected color is wrong, investigate that variant's image association. Do not change both resources merely because the same photograph happens to appear in both contexts.
Preserve the approved source files and current assignments before an authorized API update. The product-image and variant-image endpoints require the appropriate store credentials and permissions. Creative preparation is not equivalent to catalog publication.
After changing one relationship, inspect the intended storefront context and verify that the unrelated context remains correct.
Hypothetical backpack image map
Hypothetical exercise. No BigCommerce API call or theme test was performed. A fictional product has ID 9200 and two variants: 92001 for SKU PACK-NAVY-20, and 92002 for SKU PACK-OLIVE-20.
The merchant approves pack-family-main.png as the product listing thumbnail. The navy variant should use pack-navy-front.png, and the olive variant should use pack-olive-front.png.
In the proposed failure scenario, the listing thumbnail is correct but selecting Olive still displays the navy front photograph. The repair target is the olive variant-image association, not the thumbnail flag.
| Role | Expected file | Actual observation |
|---|---|---|
| Product thumbnail | pack-family-main.png | Not checked |
| Navy variant | pack-navy-front.png | Not checked |
| Olive variant | pack-olive-front.png | Not checked |
Branch by where the wrong image appears
If the product listing card is wrong while both selected variants are correct, review is_thumbnail and the product-image resource. Do not overwrite variant assignments to repair the listing card.
If the thumbnail is correct but Olive shows Navy, verify variant ID 92002 and its associated image. A mistaken variant ID is a catalog mapping problem, not a source-photo problem.
If the API relationships are correct but the actual storefront still displays an unexpected image, record the theme and selection path. Investigate presentation logic before making repeated data changes.
The image-role guideswatch guide
CartVisual does not modify BigCommerce image flags, variant associations, or storefront themes.
Use the example with your own product records
The filled records are hypothetical editorial examples. The entry-template row is for your own files, settings and observations; it does not connect to another application.
| Product ID | Role | Variant ID | Fictional SKU | Expected image | Actual API observation | Actual storefront observation | Next action |
|---|---|---|---|---|---|---|---|
| 9200 | Product thumbnail | Product family | pack-family-main.png | Not checked | Not checked | Inspect is_thumbnail | |
| 9200 | Variant | 92001 | PACK-NAVY-20 | pack-navy-front.png | Not checked | Not checked | Verify Navy selection |
| 9200 | Variant | 92002 | PACK-OLIVE-20 | pack-olive-front.png | Not checked | Not checked | Verify Olive association |
What the sources establish
- BigCommerce: Catalog Overview: Verified product images, is_thumbnail, one-thumbnail limit, and separate variant-image resource.
- BigCommerce: Create Product Variant Image: Verified variant-specific image association and replacement behavior.
Sources and further reading
Recorded source-review dates are listed individually below. An undated source does not inherit the article’s publication date. Software and platform rules can change; check the current original before acting.
- BigCommerce: Catalog Overview · Review date not separately recorded
- BigCommerce: Create Product Variant Image · Review date not separately recorded
Frequently asked questions
Does is_thumbnail control every variant image?
No. BigCommerce documents is_thumbnail on product images and a separate resource for variant image associations.
Should I change the product thumbnail when one color displays the wrong image?
First inspect the selected variant's explicit image association. Change the product thumbnail only if that product-level role is also wrong.
YOUR NEXT CAMPAIGN
Create assets from a clear source
Bring your reviewed source photo or brand brief to CartVisual. Check the current tools, account access and credits before generating, then compare every result with your source.
Create a CartVisual account Open the workspace Check access and credits