Skip to main content
The returned images on a product in the Storefront API are a subset of the imported product images, affected by the Product Card configuration in the Experience app. The Hover effect setting in the Product Card configuration determines how many images are returned and in which order. The hover effect has three settings:
  • Show image gallery on hover, which returns the configured number of images. Can be used to create a slideshow on the product card.
  • Swap images on hover, which returns two images. The second image is intended to be shown when hovering over the image in the UI.
  • No hover effect, which only returns one image.
The hover effect setting will always be gallery on product pages, and all images will be returned.
The image prioritization can be based on image type (cutout, model, or misc) as well as image tags. You can specify the order for each setting in Experience app → Pages → Settings .
Swap has separate priorities for the idle and hover image.
You can set the initial type of an image with the type_default attribute, specifying model, cutout, or misc to ensure the image has a type from the start, before the automatic image analysis completes. If you don’t want the type to be overridden by the image analyzer, use the type_override attribute instead. If you specify the order “Cutout[1], Model[1], TAG”, the first Cutout image will be chosen before the first Model image, and the image with the tag “TAG” will have the lowest priority. Images that are down or unreachable by us will not be returned, unless all images are unreachable, in which case only one image will be returned. Images that only have small resolutions (100 pixels wide or less) will only be returned as thumbnails. Another situation is when only one picture is present, but a hover effect that requires more than one image has been configured. In this case, only one image is returned, and the effect of the image is set to NONE in the Storefront API. More information on how to work with tags on images can be found in the image tags guide.
Last modified on September 3, 2026