Product media in the Products V3 API includes images and videos that showcase your products to customers. Media can be associated with products at multiple levels: at the product level for general product imagery, and at the option choice level to display specific images when customers select different options like colors or materials.
The media object in a product contains 2 main components:
main: Read-only. The product's primary image, automatically set to the first item in the itemsInfo.items array. To change the main media, reorder the items array.itemsInfo.items: An array of up to 15 media items associated with the product. Supports images and videos.When creating or updating a product, pass media items in the media.itemsInfo.items array. For each media item, provide either:
id: The ID of an existing file in Wix Media Manager.url: An external media URL.The following example shows a product media object with 2 items: one using a Wix Media Manager file ID, and one using an external URL. The first item becomes the product's main media:
When you set media using a Wix Media Manager id, the image or video field is populated with details like the actual URL, dimensions, and file size. This is useful because the id alone doesn't give you the URL needed to display the media. When you set media using an external url, these fields aren't populated since the system doesn't have metadata for external files.
Option choices and modifier choices can have linked media that displays when a customer selects that choice. This is useful for products with visual variations like color options.
Linked media references images from the product's media.itemsInfo.items array. Each choice has a linkedMedia array that specifies which images to display when a customer selects that choice.
When a customer selects choices from multiple options, only media that appears in the linkedMedia of all selected choices is displayed.
For example, consider a product with a Color option and a Gift Wrap modifier:
When a customer selects both "Red" and "Premium Box", only Images 2 and 3 are displayed because they appear in both linked media arrays.
The following example shows a t-shirt product with a Color swatch option and a Gift Wrap modifier. Each color choice has linked media that displays when selected. The Gift Wrap modifier's "Premium Box" choice also has linked media. Since the product has 2 colors, it includes 2 variants:
Each variant has a read-only media object. This is automatically set based on the linkedMedia of the variant's option choices, or defaults to the product's main media if no linked media is configured.
For digital products, each variant can have a digitalFile in its digitalProperties. This is a SecuredMedia object used for downloadable content and is separate from the product's display media.