Shopify field mapping

Shopify images to image_link

variant.image / product.images image_link

image_link should be the variant's own image where one is assigned and the product's featured image otherwise, served at full size from the Shopify CDN. The mapping decisions that matter are which image each row gets, and not shrinking it on the way out.

The Shopify side

API field: variant.image / product.images
Called: Product media and variant image
Found at: Product → Media, and the image assigned to each variant in the variant editor
Feeds: image_link

Before and after

Real values on the left as Shopify stores them, on the right as a channel needs them.

Example transformations for Shopify images to image_link
In Shopify	In the feed	Note
variant image assigned	https://cdn.shopify.com/s/files/1/.../oxford-black.jpg	The variant's own image, at original size.
no variant image, featured image set	https://cdn.shopify.com/s/files/1/.../oxford-main.jpg	Correct fallback rather than an empty value.
theme URL with _400x400	the same URL without the size suffix	Size parameters stripped so the channel gets the full-resolution file.
media: 1 video, 3 images	the first image, then the other two as additional_image_link	Video filtered out; it is not an image URL.
no media at all	(row excluded)	image_link is required everywhere, so the item cannot be submitted.

The transformation, step by step

Prefer the variant image, fall back to the featured image

A black shirt row should show the black shirt. Shopify lets a variant carry its own image, and where one is assigned it is the right value. Where none is, the product's featured image is the correct fallback rather than an omission.
Send the original, not a theme size

Shopify CDN URLs accept size parameters, and theme code appends them. A feed that inherits a 400-pixel variant sends a thumbnail to a channel that wants the largest image available, and several channels reject undersized images outright.
Use an absolute HTTPS URL

A protocol-relative or relative URL cannot be fetched from a feed. The CDN serves HTTPS, so the value should be fully qualified with no redirects in front of it.
Fill additional_image_link from the remaining media

The other product images go into additional_image_link, in the order they appear in the admin, excluding the one already used as the primary. Videos and 3D models are not images and must be filtered out rather than passed through.
Decide what happens with no image at all

image_link is required on every channel, so a product with no media cannot be submitted. Excluding those rows deliberately is better than shipping a broken URL or a placeholder graphic, which breaches image policy on several channels.

What goes wrong

Theme size parameters shrink the feed image

Shopify image URLs carry an optional size suffix, and code copied from a theme brings it along. The feed then advertises a 400-pixel thumbnail, which looks acceptable in a spot check and fails a minimum-resolution check on channels that enforce one.

Variant images are often only assigned for colours

Merchants assign images per colour and leave the size variants sharing them, which is sensible. A mapping that requires a variant image will drop most rows, so the fallback to the featured image is not an edge case but the normal path.

Promotional overlays breach image policy

Badges, sale banners and watermarks added to product images are against image policy on several channels even when the URL works perfectly. Where a store has those, a clean alternative has to be found in the media list rather than generated.

A crawl failure is not always a wrong URL

Image crawl errors also come from rate limiting, from a firewall rule that blocks the channel's crawler, or from a CDN configuration that varies by region. The URL being correct in a browser does not prove the channel can fetch it.

How feedlab maps it

feedlab resolves the primary image as variant image first and featured image second, strips any CDN size parameters so the original is served, and fills additional_image_link from the remaining images in admin order with videos and 3D models excluded. Products with no usable image are listed rather than shipped with a broken URL.

Frequently asked questions

Which image should a variant row use?

The variant's own image where one is assigned, and the product's featured image otherwise. Most stores assign images per colour only, so the fallback is used on the majority of rows.

Why are my feed images being rejected as too small?

Almost always a Shopify CDN size parameter inherited from theme code. Strip the suffix so the original file is served rather than a resized version.

How do I send more than one image?

In additional_image_link, in the order the media appears in the admin, excluding the image already used as image_link. Filter out videos and 3D models, which are not image URLs.

What if a product has no image?

It cannot be submitted, because image_link is required on every channel. Excluding the row deliberately is better than a placeholder graphic, which breaches image policy in its own right.

Errors this mapping causes

Image link cannot be crawled An image crawl failure means the channel could not retrieve the file at image_link, or retrieved it and judged it unusable. On Shopify the URL itself is rarely wrong, so the cause is usually a rate limit hit during a first full crawl, a temporary CDN response, or an image whose content breaks policy rather than one that is genuinely missing.

Attributes involved

image_link The image_link attribute is the URL of the single main image a channel shows for an item. On Shopify the correct source is the variant's own image where one is assigned, falling back to the product's featured image, because a feed that shows the wrong colour is worse than one that shows a generic shot.

Related concepts

Variant-level feed A variant-level feed emits one row for each purchasable variant rather than one row per product, because sales channels treat every size, colour and material as a separately buyable item with its own price, stock and barcode. A Shopify product with four sizes in three colours is one product in the admin and twelve items to a channel.

Primary sources

Channel specifications change. These are the official documents this page is based on.

Last reviewed 18 September 2026 View as markdown