Item group: linking product variants together

Definition

An item group is a shared identifier that groups together different variants of the same underlying product, such as different sizes or colours of one T-shirt design, so that a shopping channel understands they belong together and can display them as a single product with variant options.

Why item groups matter

Shopping channels use the item_group_id field to recognise which product records represent variants of the same item. When channels receive product data with matching item_group_id values, they display a variant selector on the listing or advertisement instead of showing each variant as a separate, unrelated product.

This affects both customer experience and your inventory management. A customer browsing a shoe listing expects to see a colour selector that lets them choose between black, navy, red, and white versions without leaving the page. Without proper item group linking, each colour appears as a distinct product in search results, which looks messy and makes it harder for customers to find what they want.

From an inventory perspective, channels can consolidate stock levels across variants when they recognise them as part of the same item group. This helps with accurate stock display and reduces the risk of overselling.

How item groups work in practice

Suppose you sell a running shoe in five colourways: black, navy, red, white, and grey. Each colourway is a separate product record in your system because each has its own SKU, barcode, and inventory level.

To link these variants together, you assign the same item_group_id value to all five records. For example:

Each variant retains its own unique product identifier (SKU and GTIN) so the channel can track inventory and orders separately. But because all five records share the item_group_id value 'running-shoe-v1', the channel recognises them as variants of the same product and displays them with a colour selector on a single listing.

A technical constraint to remember

Vendably stores each product variant as a separate record. There is no built-in parent / child hierarchy tree where one 'parent' product contains multiple 'child' variants. Instead, item group linking depends entirely on the consistency of the item_group_id value across all the variant records in your feed.

If one variant has item_group_id set to 'running-shoe-v1' but another has 'running-shoe-v2', channels will not recognise them as variants of the same product. They will display as separate items. This means you must ensure the item_group_id is identical and consistent across every variant record that should be grouped together.

Related terms

Understanding item groups requires familiarity with related concepts:

Product identifier: A unique code that distinguishes one product record from another. Common examples are SKU (your internal code) and GTIN (the barcode number). Each variant must have its own unique product identifier so the channel can track stock and process orders correctly.

GTIN: The Global Trade Item Number, typically a barcode or EAN code. Each variant of a product usually has a different GTIN, even though they share an item_group_id.

Canonical category: Vendably's shared product taxonomy that classifies products into a standard category structure. Item groups and canonical categories work independently; a shoe item group belongs to a single canonical category, but the category does not determine grouping.

Summary

Item groups are the mechanism that tells shopping channels which product variants belong together. By assigning the same item_group_id value to all variants of a product, you enable channels to display a unified listing with variant selectors for colour, size, or other attributes. In Vendably, consistency is key: every variant record must carry the exact same item_group_id value for the grouping to work correctly across your feed destinations.