Variants, item_group_id and product ID matching in Meta catalogues

Meta defines variants as different variations of the same product in your catalogue. A T-shirt sold in red and blue, in small and large, has four variants: red small, red large, blue small and blue large [1]. For the catalogue this means each variant is a product row of its own, and a group ID links those rows together.

Two levels: product ID and group ID

In a data feed, the id field is the item's unique content ID. Meta recommends using the item's SKU if possible; the field is limited to 100 characters, and each content ID must appear only once in the catalogue [3]. The consequence of that last rule is harsh: if there are multiple instances of the same ID, Meta ignores all of them [3]. IDs are case sensitive, so "abc123" and "ABC123" are two different products [7].

Variants are grouped with item_group_id: you enter the same group ID for all variants of the same product [2][3]. Meta's developer documentation says this value typically corresponds to the parent SKU, although any other ID can be used [4]. The batch API reference describes item_group_id as the advertiser-supplied ID of a product group, and stresses that it is not the FBID [6].

A common mistake is to use one product's id as the group ID of other products. Meta reports this as "ID conflicts with group ID": all content IDs and group IDs in a catalogue must be unique [7].

Telling variants apart

Meta asks for at least one variant attribute to differentiate variants in a group: color, size, material, pattern, gender or additional_variant_attribute [2]. Whatever attributes you fill for one variant, fill the same ones for every variant in the group, and make sure each variant has a unique combination [2]. A different image alone is not enough to differentiate a variant [2]. All variants of the same product must belong to the same data feed [2].

In ads, only one variant of each product is shown per ad, and the delivery system picks which one; when people tap the product, they see its other variants on the product page [1].

Identifier fields on different surfaces

Identifiers appear under different field names on different surfaces:

• In a data feed and in the catalogue batch API (items_batch) the field is called id [3][6].
• In the batch API's validation results, rows are identified by retailer_id [6]. On the Graph API Product Item, retailer_id is described as "a unique identifier for this item (which can be a variant for a product)", and retailer_product_group_id as the item group ID that the product is a variant of [5].
• The same Product Item also has a numeric id assigned by Meta [5]. That value is not your identifier; matching uses the identifier you supplied.

Matching pixel events

For Advantage+ catalogue ads, the Meta Pixel must send the ViewContent, AddToCart and Purchase events. In these events, the content_ids (or contents) parameter carries a product's id or a product group's item_group_id from the catalogue [8]. The catalogue reference is explicit: the ID must exactly match the content ID for the same item in the Meta Pixel [3].

The content_type parameter is optional, but if you send it, it must match the type of ID: product for individual product IDs, product_group for group IDs [9][11]. Meta recommends product on a page about a specific variant (size, colour) and product_group on a product page where no size has been chosen yet. product_group should not be used with AddToCart or Purchase [9]. If no content_type is sent, Meta matches the event to every item with the same ID, regardless of type [9].

Catalogue match rate shows how well this works: the share of content IDs received in events that match products in a connected catalogue [10]. If several catalogues are connected to the same pixel, the rate is split between them [10]. It covers the last 28 days, with a 48-hour delay [11]. Formatting mistakes Meta lists include spelling the parameter content_id without the "s", and sending several IDs inside one string; for example ['12345,67890'] is read as a single product ID [11].

The Shopify side

For the advanced setup in which a data feed is used alongside Shopify, Meta says that, to match products correctly, the feed's id field should contain each product's Shopify variant ID [12].

Before you change an ID

When adding variants to an existing product, Meta recommends that one variant keeps the product's original id, so that Meta Pixel event data for the product is preserved; changing the ID can hurt ad performance [2]. If you change group IDs and your pixel sends group IDs, update the values in your pixel code as well [7].