---
title: >-
  Show image swatches for product options in the Catalog API - Shopify developer
  changelog
description: >-
  Shopify’s developer changelog documents all changes to Shopify’s platform.
  Find the latest news and learn about new platform opportunities.
source_url:
  html: >-
    https://shopify.dev/changelog/posts/show-image-swatches-for-product-options-in-the-catalog-api
  md: >-
    https://shopify.dev/changelog/posts/show-image-swatches-for-product-options-in-the-catalog-api.md
metadata:
  effectiveApiVersion: ''
  affectedApi: []
  primaryTag:
    displayName: Catalog
    handle: catalog
  secondaryTag:
    displayName: Update
    handle: update
  indicatesActionRequired: false
  createdAt: '2026-11-19T12:21:33-05:00'
  postedAt: '2026-11-19T15:00:00-05:00'
  updatedAt: '2026-11-20T14:53:41-05:00'
  effectiveAt: '2026-11-20T12:00:00-05:00'
---

November 19, 2026

# Show image swatches for product options in the Catalog API

DateNovember 19, 2026

FlagsUpdate

TagsCatalog

The Catalog API can now return an image for each product option value, such as a color, so you can show buyers a picture of each choice instead of only its name. Swatches are available when you request full product details with `get_product`. The new field is optional, and existing integrations keep working without changes.

## What changed

In a `get_product` response, an option value can include a `swatch` object. Each `swatch` has one field, `image_url`, which is the URL of an image that represents the option value. Not every option value has a swatch. When a value has no swatch data, the response omits `swatch`.

`search_catalog` and `lookup_catalog` don’t return swatches, and swatches aren’t part of a variant’s `options` array. You don’t need to change your agent profile to get them.

## Who’s affected

You’re affected if your app or agent calls `get_product` and shows product options to buyers, for example in a variant picker on a product page. If you only call `search_catalog` or `lookup_catalog`, nothing changes.

## What to do

No action is required. If you don’t read `swatch`, your integration keeps working as before.

To show swatches:

1. Read `product.options[].values[].swatch.image_url` from the `get_product` response.
2. Show the image beside the option value or in its place, and keep the `label` visible or available to screen readers.
3. When a value has no `swatch`, or its image doesn’t load, show the `label`.
4. Use `available` and `exists` to set each option’s state. Don’t treat a missing swatch as an unavailable option.

## Related docs

* [Option swatches in the Global Catalog extension reference](https://shopify.dev/docs/agents/catalog/global-catalog-extension#option-swatches)
* [`get_product` in the Global Catalog MCP reference](https://shopify.dev/docs/agents/catalog/global-catalog#get_product)
