Product media

Everything attached to a product, gallery first and then the samples. Each row carries its kind (image, video, audio, document or embed), its role (gallery, sample, or label for the files a product label is made of), the stored path and site-relative url, or the embed url for a third-party player, plus mime, bytes, duration in seconds, alt text, position and the resolved poster image. Narrow with role or kind. Uploading bytes is not available through this interface; an embed is, because it has none.

The compatibility view of the above: a product's gallery pictures alone, each as id, stored path, site-relative url, alt text and position. This is what a client written before product media existed means by "images", and it never returns a clip, a sample or an embed.

Attach a third-party video by URL. No bytes are uploaded: the row holds the canonical embed URL, and the storefront draws a click-to-load placeholder that fetches nothing from the video host until a shopper presses play. The host has to be on the store's media.embed_hosts allowlist (YouTube, YouTube nocookie and Vimeo by default) and the URL has to be https, or the call is refused with a 422. A watch, share or shorts URL is accepted and stored in its embed form. A poster has to be a gallery image of the same product.

Change a row's alt text, its place in its list, its recorded duration, its poster, or an embed's URL. The bytes are immutable, so replacing a file means uploading a new one and deleting the old. An empty alt string declares a picture decorative. The role is not editable: moving a video from the gallery to the samples means deleting it and adding it where you want it.

Put a product's gallery, or its samples, in the order of the ids given, in one transaction. The first gallery image is the product's main picture, so naming an image first makes it the main one. Rows of that list left out keep their order after the ones named. Every id must be a row of this product in that role, or nothing is changed.

Detach a row from its product and delete the bytes on disk, where there are any. Every option value, variant and poster pointing at it is cleared at the same time.