Product media
Media records hold reusable asset information. Product variants associate those records and control their presentation order, keeping the asset lifecycle separate from catalog placement.
Lifecycle
Create or upload the media record first, then attach its ID to one or more variants with productVariantsMediaAdd. Use productVariantsMediaReorder when the gallery order changes and productVariantsMediaRemove to detach an asset without deleting the media record itself.
Deleting media is a stronger operation than removing a variant association. Before deletion, inspect every owner that may still reference the record. A storefront should tolerate a missing optional asset and retain text, price, and availability content.
Variant and hero presentation
Attach images that describe a particular option—such as the blue finish—to that variant. When a buyer changes the selected variant, the storefront can render its ordered media. The product’s heroVariant provides the featured variant used for product-level presentation; do not assume that every variant shares the same gallery.
Delivery
The stored media URL identifies the source asset. Derive responsive renditions with Thor’s image URL parameters rather than uploading a separate file for each viewport. Preserve the original URL as a fallback and include useful alternative text in the consuming experience.