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 > 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.
*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 nompn is assigned)
Required
(if nompn 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 setisMarketplace 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 setisMarketplace 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.
