Shopify field mapping

Shopify variant ID to id

variant.id id

The feed id must be unique per row, stable forever, and present on every item, which makes the Shopify variant id the safest source. A SKU is more readable but is neither guaranteed unique nor guaranteed to exist, and changing an id later costs the item its accumulated history.

The Shopify side

API field: variant.id
Called: Variant ID
Found at: Not shown in the admin. Exposed through the API, and visible in the URL when editing a variant.
Feeds: id

Before and after

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

Example transformations for Shopify variant ID to id
In Shopify	In the feed	Note
variant id 43215678901234	43215678901234	Unique, stable and always present. Sent as a string.
SKU "SHIRT-BLK-M"	SHIRT-BLK-M	Readable, and only safe once you have verified every SKU exists and is unique.
SKU empty on 400 variants	(missing id)	Why SKU-based ids fail: the attribute is required on every row.
Same SKU on two variants	(duplicate id)	Shopify permits it. The channel keeps one row and drops the other.
variant id, prefixed	SHOP-43215678901234	Fine, as long as the prefix never changes again.

The transformation, step by step

Use the variant id, not the product id

A variant-level feed has one row per variant, so the id must vary per variant. The product id repeats across every size and colour, which produces duplicate ids and makes the channel keep one arbitrary row.
Prefer the variant id over the SKU

SKUs are optional in Shopify, are frequently duplicated across variants, and get rewritten during stock system migrations. The variant id is assigned by Shopify, always present and never reused, which is exactly what the attribute asks for.
Add a prefix only if you need one, and keep it forever

A prefix such as SHOP- makes ids recognisable in reports. It also becomes part of the identity of every item, so it cannot be changed later without resetting the history of the entire catalogue.
Send it as a string

Shopify ids are long integers. Treated as numbers they can reach a spreadsheet or a JSON parser and come back in scientific notation or subtly rounded, so the value should be a string from the moment it leaves the catalogue.
Never reuse an id for a different product

An id carries the item's performance history on the channel. Reusing one for an unrelated product inherits that history, and deleting and recreating a product in Shopify produces a new variant id, which correctly reads as a new item.

What goes wrong

Shopify does not enforce unique SKUs

Two variants can carry the same SKU, and in a catalogue built by several people over years, some do. A SKU-based id then produces duplicates, the channel keeps one of the rows arbitrarily, and the missing products are hard to notice because nothing is reported as an error.

Changing the id resets the item

The id is the item's identity on the channel. Switching from SKU-based to variant-id-based ids across a live catalogue retires every item and creates a new one, losing the performance history. It is sometimes the right migration, but it is never a small change.

Large integers get mangled

A Shopify id is long enough to lose precision as a float. Passing a feed through a spreadsheet, or letting a JSON encoder treat the value as a number, can round it or render it in scientific notation, producing ids that match nothing.

Product ids produce silent duplicates

Mapping the product id instead of the variant id is a one-character mistake that collapses every variant of a product into one row. The feed validates, the item count is simply lower than expected, and that is the only visible symptom.

How feedlab maps it

feedlab uses the variant id as the default feed id, as a string, with an optional prefix fixed at setup. Where a store insists on SKU-based ids the preview reports every duplicate and every empty SKU before publishing, since those are the two failure modes and both are invisible in the channel's own error report.

Frequently asked questions

Should the feed id be the Shopify variant ID or the SKU?

The variant ID is safer: always present, unique, and never reused. A SKU is more readable, but Shopify does not require it or enforce uniqueness, so a SKU-based id can be missing or duplicated.

Can I change the feed id format later?

You can, but every item is retired and recreated, losing its performance history on the channel. Decide the format at setup and keep it.

Why does my feed have fewer items than my catalogue?

A common cause is duplicate ids, either from mapping the product id instead of the variant id, or from repeated SKUs. The channel keeps one row per id and silently drops the rest.

Does the id need to be a number?

No, and it is safer as a string. Shopify ids are long integers that can lose precision if anything downstream treats them as numeric.

Errors this mapping causes

Duplicate product id A duplicate id error means two or more rows in a feed claim the same identifier, so the channel cannot tell which one describes the item and keeps only the last it processed. On Shopify it usually means the feed was built per product rather than per variant, or that a SKU used as the id is blank or reused across variants.

Attributes involved

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