Skip to main content

Show image swatches for product options in the Catalog API

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

Was this page helpful?