Shopify field mapping

Shopify product ID to item_group_id

product.id item_group_id

item_group_id is what tells a channel that several rows are variants of one product, and the Shopify product id is the natural source because every variant of a product shares it. The exception is a store whose variants are modelled as separate products, where the grouping has to come from somewhere else.

The Shopify side

API field: product.id
Called: Product ID
Found at: Not shown in the admin. Exposed through the API, and visible in the URL when editing a product.
Feeds: item_group_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 product ID to item_group_id
In Shopify	In the feed	Note
product id 7891234567890, 6 variants	7891234567890 on all six rows	The standard case: one product, six grouped rows.
product id, single variant	(omitted)	Nothing to group, so the attribute says nothing.
three products sharing style "OXF-100"	OXF-100	Colour-per-product modelling. Grouped by a style metafield rather than the product id.
product id (OpenAI feed)	group_id 7891234567890 plus listing_has_variations true	Same grouping, different field name and an extra flag.

The transformation, step by step

Send the product id on every variant row

All variants of a Shopify product share its id, which is exactly the grouping the attribute describes. Send it as a string, for the same reasons the feed id is a string.
Omit it for products with a single variant

A product with one variant is not a group. Sending the attribute anyway is harmless on most channels but says nothing, and omitting it keeps the feed honest about which products actually offer a choice.
Group across products where the store models variants that way

Stores often create separate products per colour, each with size variants, so a shared group needs a value the products have in common. A metafield holding a style code is the usual answer, and collection membership is a weaker fallback.
Keep the group value stable

The group is part of how the channel understands your catalogue. Changing the value regroups the items, which resets the relationship between them even when every individual row is unchanged.
Use the right field name per channel

Google, Meta, Microsoft and Pinterest all call it item_group_id. OpenAI calls it group_id and additionally wants listing_has_variations and a variant_dict, so the same grouping decision produces a different shape there.

What goes wrong

Colour-per-product catalogues group nothing

When each colour is its own Shopify product, the product id groups only the sizes within that colour. The channel then shows five unrelated listings for one style, competing with each other, and the feed looks perfectly valid throughout.

Using the variant id groups nothing at all

Mapping the variant id into item_group_id gives every row its own unique group, which is the same as sending nothing while appearing to be correct. It is a single-character mistake that removes every variant picker in the catalogue.

Grouped items must actually be variants

The attribute groups the same product in different sizes, colours or materials. Grouping genuinely different products, such as a whole collection, misrepresents the catalogue and can be treated as misuse rather than as a mistake.

Apparel needs it more than the specification suggests

It is formally conditional, but an apparel listing without grouped variants loses the size and colour picker entirely, which is most of what makes the listing work in that vertical.

How feedlab maps it

feedlab defaults item_group_id to the Shopify product id for multi-variant products and omits it for single-variant ones. Where a catalogue models colours as separate products, a metafield can be nominated as the group source instead, and the preview shows how many rows end up in each group so an ungrouped style is visible before publishing.

Frequently asked questions

What should item_group_id be for a Shopify feed?

The Shopify product id, sent as a string on every variant row. All variants of a product share it, which is exactly the grouping the attribute describes.

My colours are separate products. What do I group by?

A value the products share, normally a style code in a metafield. The product id only groups the sizes inside one colour, so the style never appears as a single grouped listing.

Do single-variant products need item_group_id?

No. There is nothing to group, and omitting it keeps the feed accurate about which products actually offer a choice.

Is item_group_id the same on every channel?

Google, Meta, Microsoft and Pinterest use that name. OpenAI calls it group_id and also expects listing_has_variations and a variant_dict describing what varies.

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