Shopify’s latest developer update adds a simple yet powerful visual cue to product option pickers. By including an optional swatch object in the get_product response, the Catalog API can now return an image URL for each option value—think color chips, pattern thumbnails, or fabric samples. This post breaks down exactly what changed, who needs to pay attention, and how you can start showing image swatches on your storefronts without breaking existing code.
What Changed
When you request full product details with the get_product endpoint, each option value may now include a new nested object called swatch. The object contains a single field, image_url, which points to a hosted image that represents the option value. For example, a “Red” color option could return:
"options": [{
"name": "Color",
"values": [{
"value": "Red",
"swatch": { "image_url": "https://cdn.shopify.com/s/files/1/…/red-swatch.png" }
}, {
"value": "Blue"
// No swatch – field omitted
}]
}]
If an option value does not have an associated image, the swatch key is simply omitted, keeping the payload lightweight. Importantly, only the get_product endpoint returns swatches; calls to search_catalog or lookup_catalog remain unchanged, and swatches are not part of a variant’s options array.
Who’s Affected?
*Developers & app builders* – If your integration calls get_product and renders option selectors (e.g., a custom variant picker, a mobile app UI, or a headless storefront), you can now surface visual swatches alongside the textual label. No changes are required for apps that only use search_catalog or lookup_catalog.
*Merchants* – The update is transparent to merchants unless they or a third‑party app choose to display swatches. The storefront experience can become more engaging, especially for color‑heavy catalogs.
Do You Need to Take Action?
Short answer: No immediate action is required. Existing integrations that ignore the new swatch field will continue to work exactly as before. However, to unlock the visual benefit, you’ll want to read the field and render the image when it exists.
How to Implement Swatches
get_product endpoint with the fields parameter set to include options (the default includes it).GET https://{shop}.myshopify.com/api/2024-07/catalog/products/{product_id}?fields=options
product.options[].values[]. For each value, check if swatch exists and read swatch.image_url.product.options.forEach(option => {
option.values.forEach(val => {
const img = val.swatch?.image_url;
// img will be undefined if no swatch is provided
});
});
aria-label or visually hidden spans so screen readers still announce the option name.<button class="option" aria-label="Red">
<img src="{{val.swatch.image_url}}" alt="Red" class="swatch" />
<span class="visually-hidden">Red</span>
</button>
swatch is absent or the image fails to load, fall back to the plain text label. This ensures you don’t mistakenly mark an option as unavailable.available and exists flags (if you expose them) to control selection. A missing swatch should never change the availability logic.Best Practices & Accessibility
alt="" on decorative images and provide a descriptive aria-label on the interactive element.?width=64).image_url locally or via a CDN to reduce latency on repeat views.Related Documentation
* Option swatches in the Global Catalog extension reference – detailed field definitions.
* get_product in the Global Catalog MCP reference – full request/response schema.
* Shopify Image CDN guide – how to resize or format swatch images for fast loading.
Conclusion & Next Steps
The addition of image swatches to the Catalog API gives headless merchants and app developers a low‑effort way to make product pickers more visual and shopper‑friendly. Because the field is optional and backward‑compatible, you can roll out swatches incrementally—start with a single high‑impact collection, monitor performance, and then expand site‑wide.
Ready to level up your product selectors? Pull the latest get_product payload, add a few lines of rendering logic, and watch conversion rates climb as shoppers instantly recognize the option they want. If you run into any quirks or want to share your implementation, drop a comment below or reach out on the Shopify Community forums.
