Product dataset parameters

You will find on this page a comprehensive list of parameters that can be sent to the Product Importer API.

The required parameters will prevent product ingestion if they are left blank or not included.
The recommended parameters will significantly improve performance if present.

📘
Please note that the product dataset parameters are largely similar to those of the product feed; however, the spelling of some parameters may differ (e.g., image_link in the feed corresponds to imageLink in the Product Importer). You can find the full list of the product feed parameters on this page.

⚠️
A product limit is set to 256KB, meaning the total size of all parameters for a single product must not exceed 256KB, otherwise, the product will be discarded.

Basic product data

Parameter name	Onsite	Offsite	Description
`id`	Required	Required	Definition: The ID is a unique product identifier that represents only one product. If multiple products are multiple variants of the same product, each variant should have a unique ID. Specifications: - Must be unique and consistent; changes to product IDs will break attribution and reporting. - Cannot match `item_group_id`. - Must match with the data shared in OneTag/API calls. - Quotation marks, non-ASCII characters, and the hyphen symbol (-) are not supported. - Will default to lowercase in our ad response if using alphanumeric IDs. - Limit: `50` - Type: `String` - Sample Value: `25c48`
`title`	Required	Required	Definition: The `title` is the product’s name, typically as it is displayed on the product’s detail page.This will be used as the main text descriptor in the banners for a given product. Specifications: - Must start with a letter or number. - Limit: `500` - Type: `String` - Sample Value: `Working Boots – Size 7.5`
`description`	Required	Required	Definition: The `description` is a short piece of text that gives more information about a product in addition to its name. Because of the design of the banners, shorter descriptions (under 50 characters) are more likely to fit in Criteo’s formats and layouts, however, not all formats and layouts will have a description. Specifications: - The description must start with a letter or number. Remove all HTML tags from this field, including style, embed, object, and anchor tags. - Limit: `5000` - Type: `String` - Sample Value: `"Excellent for daily use"`
`link`	Required	Required	Definition:The `link` is the dedicated detail page for the product and is usually unique to a given product. The product information on this URL should match the corresponding information provided in your catalog. Specifications: - The `link` must start with the protocol (http:// or https://) followed by the full URL of the product detail page. - All symbols must be encoded. For example, “$” must be replaced with “%24”. - Limit: `2000 characters`, including CAT prefix + encoded URL. - Type: `String`. - Sample Value: `https://www.example.com/ProductA`
`imageLink`	Required	Required	Definition: Link to an image of the SKU Specifications: - Limit: `2000 characters`. - Size: Recommended: minimum `800x800 pixels` and weight under 16MB. - Supported formats: `PNG`, `JPEG`, or `GIF`. - Example: `https://www.example.com/image.png`
`brand`	Required Blank values in this field will prevent the SKU from being added to campaigns.	Recommended	Definition: Brand of the product Specifications: - Must be consistently set across products: changes to brand values will break campaign attribution and reporting. - Maximum of `70 characters`. - Must start with either a letter or number. - Recommended: only ASCII characters. - Non-ASCII version of the brand can be added as an extra parameter. - Example: `Adidas`

Price and availability

Parameter name	Onsite	Offsite	Description
`price`	Required	Recommended	Definition: The standard price of the product before any discounts or promotions are applied. Specifications: - The decimal separator must be a period (.) with no thousands separator. - Limit: `14` - Type: `Number` - Sample Value: `19.99`
`salePrice`	Recommended	Recommended	Definition: The final price of the product after applying a discount or promotional offer. Specifications: - Decimal separator must be a period (.) with no thousands separator. - Limit: `14` - Type: `Number` - Sample Value: `49.99`
`availability`	Required	Recommended	Definition: The availability indicates if the product may be purchased on the site. You may populate availability with three possible values: `preorder` (item is not currently shipping and you are not accepting orders for this item), `out of stock` (item is not shipping and you are not accepting orders for this item), and `in stock` (item is shipping and orders may be placed for this item). Items marked as out of stock will be excluded from being shown on the banners. Specifications: - The availability must be populated with one of the following three values: preorder, out of stock, or in stock. - Limit: `25` - Type: `String` - Sample Value: `in stock`

Product category

Parameter name	Onsite	Offsite	Description
`productTypes`	Required Must match client architecture website to display relevant ads depending where you are	Required	Definition: The categorization of the product on your website. Specifications: - Only ASCII characters. - Must start with a letter or number. - Individual levels of a path must be separated by `>` or `&gt` in the XML file. - Multiple categories should be comma-separated. - `Case sensitive`: please ensure that you use proper casing to reflect what is shown on site. - Each path should be wrapped in single quotes (`'`). - Must match your website architecture. - If multiple categories are passed: the first one must be the most relevant (main category for PDP recommendations). - Submit up to `10 categories`. - Limit: Maximum of `10240 characters`. The maximum length of an individual category node is `750 characters`. - Type: `< string > array` - Sample Value: `'Computing>Keyboards and Mice>Mice','Hardware>Input Device'`
`productTypeKeys`	Required In the output. RM TS does not explicitly request this field from retailers. Rather, it is made up from the value(s) in product_type.	Required	Definition: The corresponding category IDs for the categories passed in the `product_type` field. Specifications: - These category IDs should match those shown on the site. - Limit: Maximum of `10240 characters`. - The maximum length of an individual category node is `750 characters`. - Type: `< string > array` - Sample Value: `'123>4567>89012','456>7890'`
`googleProductCategory`	Required Not using category1/2/3	Recommended	Definition: Category level attributes indicate the category of the product being submitted, according to the Google product taxonomy. If your product can be linked to multiple categories, we only want the one that is the most relevant. Specifications: - Limit: `750` - We accept both IDs and full category path. - `Case sensitive` - Type: `String` - Sample Value: `2271 or Apparel & Accessories > Clothing > Dresses`

Product identifiers

Parameter name	Onsite	Offsite	Description
`mpn`	Required (if no `gtin` is assigned)	Required (if no `gtin` is assigned)	Description: `Manufacturer Part Number` is a unique number issued by manufacturers to identify individual products. Specifications: - The MPN of a product is a series of numbers and letters. Required for all products without a `GTIN` assigned. Only provide an `MPN` if you are sure it is correct. When in doubt, do not provide an MPN. - Limit: `70` - Type: `String` - Sample Value: `T49025028767898`
`gtin`	Required (if no `mpn` is assigned)	Required (if no `mpn` is assigned)	Definition: `Global Trade Item Number (GTIN)` is a unique product identifier used to identify a product, a service, or an item in the global marketplace. A GTIN helps Criteo make your products easier for customers to find. Products submitted without a unique product identifier are difficult to categorize and may not be eligible for all of our features. Specifications: - The value must be an 8-, 12-, 13-, or 14-digit number (UPC, EAN, JAN, or ISBN): - `GTIN-8 (EAN/UCC-8)`: this is an 8-digit number used predominately outside of North America. - `GTIN-12 (UPC-A)`: this is a 12-digit number used primarily in North America. - `GTIN-13 (EAN/UCC-13)`: this is a 13-digit number used predominately outside of North America. - `GTIN-14 (EAN/UCC-14 or ITF-14)`: this is a 14-digit number used to identify trade items at various packaging levels. - Limit: `50` - Type: `String` - Sample Value: `00012345678905`

Detailed product description

Parameter name	Onsite	Offsite	Description
`itemGroupId`	Recommended To be able not to display variants of the product in the same ads.	Recommended	Definition: Use the same value for the `item_group_id` field to group all product variants. Product variants are similar products that differ from each other only in product details (sizes, color, material, pattern, age range, or gender). This relationship establishes that the products with the same `item_group_id` are variants (or child) of the parent product (`item_group_id`). By using this field to group the products, you remove the risk of displaying duplicated products within the same banner. The `id` and `item_group_id` fields must be different. Use the `id` field to uniquely identify a single product and use `item_group_id` to group multiple products as variants. Please make sure to not mix up the `item_group_id` and `id` fields, The `item_group_id` must be chosen outside of the `id` range. If a product has the same `id` as an existing `item_group_id` or vice versa, the behavior is undefined and the updates on your products may be ignored. Specifications: - The `item_group_id` can only contain ASCII characters, and must not contain quotation marks. - Limit: `50` - Type: `String` - `Not case sensitive` - Example value: for Text feed (CSV/TSV): `Ab1234` - Example value: for XML feed: `\<g:item_group_id>Ab1234\</g:item_group_id>`
`productRating`	Recommended	Recommended	Definition: Product Rating enables the display of aggregated customer reviews on your product pages, showcasing a one- to five-star rating. This feature is available in Dynamic/Showcase and Meta Ads when the "Star Rating" or “Retailer” layout is selected. These ratings provide valuable insights for customers during their research and decision-making process, helping them make informed purchase choices. By offering this feature, you can attract more qualified shoppers to your product pages and enhance their overall shopping experience. Specifications: - Must start with a number or a letter. - Limit: `8` - Type: `String` - Sample Value: `1, 2, 3.50, 4, 4.92`, or `5`
`numberOfReviews`	Recommended	N/A	Definition: number of reviews the product has received. Specifications: - Limit: `8` - Type: `Integer` - Sample Value: `215`

Marketplace information

Parameter name	Onsite	Offsite	Description
`externalSellerName`	Required If the client is using private market and reselling a product for several sellers, the user needs to set `isMarketplace` field to true	Recommended	Definition: Name of the seller on the marketplace. Specifications: - Only required if you are a marketplace and are reselling a product for several sellers. - Limit: `200` - Type: `String` - Sample Value: `Best Shoe Store`
`externalSellerId`	Required If the client is using private market and reselling a product for several sellers, the user needs to set `isMarketplace` field to true	Recommended	Definition: A unique identifier that represents a seller on your retailer site. Specifications: - Only required if you are a marketplace and are reselling a product for several sellers. - Limit: `200` - Type: `String` - Sample Value: `seller123`

Additional attributes

Parameter name	Onsite	Offsite	Description
`regiondata`	Required only if availability is store-based.	N/A	Definition: The store IDs where the product is available and its local prices. Specifications: - This field must be included within the customAttributes object under the specific key regionData. - Limit: `200` - Type: `Object` - Sample Value: `"customAttributes": [ { "name": "regionData", "value": "'123':{'Price':'23.99'}, '456':{'Price':'27.99'}" } ]`
`customLabel0`, `customLabel1`, `customLabel2`, `customLabel3`, `customLabel4`	Recommended	Recommended	Definition: Include additional custom details about the product, a useful field for sorting, filtering, or categorizing products within the feed Specifications: - Create up to 5 custom labels, named from customLabel0 to customLabel4. - Submit only one value for each custom label attribute. - Limit: `100` - Type: `String` - Sample Value: `Best Seller`