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 . The new field is optional, and existing integrations keep working without changes.
What changed
In a response, an option value can include a swatch object. Each swatch has one field, , 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.
and 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 and shows product options to buyers, for example in a variant picker on a product page. If you only call or , nothing changes.
What to do
No action is required. If you don’t read swatch, your integration keeps working as before.
To show swatches:
- Read
from theresponse. - Show the image beside the option value or in its place, and keep the
labelvisible or available to screen readers. - When a value has no
swatch, or its image doesn’t load, show thelabel. - Use
availableandexiststo set each option’s state. Don’t treat a missing swatch as an unavailable option.