Show Image Swatches for Product Options via the Catalog API

Shopify’s Catalog API now returns image swatches for product option values, letting developers display color or pattern previews directly in pickers. Learn what changed, who it impacts, and how to implement swatches with zero‑effort updates.

Show Image Swatches for Product Options via the Catalog API
7 sections

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

  • Fetch full product data – Use the 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

  • Parse the response – Loop through 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

    });

    });

  • Render the UI – When an image URL is present, display it next to the label (or replace the label if design permits). Keep the text accessible by using 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>

  • Handle missing or broken images – If 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.
  • Respect option state – Use the existing available and exists flags (if you expose them) to control selection. A missing swatch should never change the availability logic.
  • Best Practices & Accessibility

  • Keep the original option text hidden for assistive technologies. Use alt="" on decorative images and provide a descriptive aria-label on the interactive element.
  • Optimize image size. The API returns a full‑resolution URL; consider requesting a smaller variant via Shopify’s image transformation parameters (e.g., ?width=64).
  • Cache the image_url locally or via a CDN to reduce latency on repeat views.
  • Test across devices – mobile screens benefit most from compact visual cues, while desktop layouts may prefer a side‑by‑side label.
  • * 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.

    Tags
    Sources

    Related Articles

    Embedding YouTube & Vimeo Directly via File Reference Metafields in Shopify API 2027-01

    Embedding YouTube & Vimeo Directly via File Reference Metafields in Shopify API 2027-01

    Shopify’s 2027-01 API now lets file reference metafields store YouTube and Vimeo video URLs, unlocking seamless video embeds for merchants and developers. Learn what changed, who it affects, and how to implement the new feature today.

    November 20, 20265 min
    Why Your Shopify App Must Enable IP Allowlist by Tomorrow (Nov 20 2026)

    Why Your Shopify App Must Enable IP Allowlist by Tomorrow (Nov 20 2026)

    Shopify’s latest security deadline forces public and custom apps to add an IP allowlist. Learn what changed, who’s impacted, and step‑by‑step how to stay compliant before the November 20 cut‑off.

    November 19, 20265 min
    Multiple Error Reporting Now Available for Function Settings Extensions

    Multiple Error Reporting Now Available for Function Settings Extensions

    Shopify’s latest developer update lets function‑settings extensions return several validation errors at once, giving merchants instant feedback on every issue. Learn what changed, who it impacts, and how to implement the new AggregateError pattern today.

    November 19, 20265 min
    Why Network Access Declarations Are Now Mandatory for Online Store Apps

    Why Network Access Declarations Are Now Mandatory for Online Store Apps

    Shopify now requires apps that run on the online store to declare their network access in shopify.app.toml. Learn what changed, who’s affected, and how to update your app before the December 2026 deadline.

    November 19, 20264 min