Product Importer API

• URLs relative to: AMERICAS: api.us.criteo.com APAC: api.as.criteo.com EMEA: api.eu.criteo.com*

Authenticate

POST /oauth2/token

Get the token necessary to perform any action through our API.
Please see the dedicated guide for Authentication

Batch

POST /preview/catalog/products/batch

Request an asynchronous batch operation of insertions, updates, and deletes. Returns the location of the report of the operation

Report

GET /preview/catalog/products/batch/report/{operation-token}

Get the report of the batch processing

POST

/oauth2/token

Get the token necessary to perform any action through our API

client_id (mandatory)
client_secret (mandatory)
grant_type (mandatory)

The token will be valid for 900s

Body

ProductsCustomBatchRequest
optional

Defines a batch of operations

ProductsCustomBatchRequest

Path

operation-token
required

The token returned by the batch endpoint

String

name required

The name of the attribute. Underscores will be replaced by spaces upon insertion.

String

value
required

The value of the attribute.

String

code required

A MACHINE-READABLE error code string in kebab-case. Unique across Criteo

String

detail
required

A HUMAN-READABLE detailed explanation specific to this occurrence of the problem.This should not be more that 1 paragraph

String

instance
required

A MACHINE-READABLE URI reference that identifies the specific occurrence of the problem. This could be useful when we want to the return the API Endpoint identifying the exact resource related to the error.

String

title
required

A short, HUMAN-READABLE summary of the problem type. It should not change from occurrence to occurrence of the problem, except for purposes of localization.

String

traceId
required

The MACHINE-READABLE correlation ID provided by the gateway

String

type
required

A MACHINE-READABLE code specifying error category. This information is used on client side to focus on certain type of error, to either retry some processing or display only certain type of errors.

String

errors required

List of errors

< Error > array

warnings
optional

List of warnings

< Warning > array

id required

A unique identifier for the item. Aka Product ID.
Case-insensitive, no quotation marks, ASCII characters, cannot match item_group_id, seller_id, (50 UTF8 characters max).

string

offerId
optional

Not used by Criteo.

string

title
required

Title of the item. (max 500 UTF-8 chars).

string

description
optional

Description of the item. RECOMMENDED. (max 5000 UTF-8 chars).

string

link
required

URL directly linking to your item's page on your website. (2000 UTF8 characters max)

string

imageLink
required

URL of an image of the item. Supported formats: PNG, JPEG, GIF. (max 2000 UTF-8 chars).

string

additionalImageLinks
optional

Additional URLs of images of the item.(2000 UTF8 characters max)

string array

contentLanguage
optional

The 2-letter ISO 639-1 language code for the item.

string

targetCountry
optional

The CLDR territory code for the item.

string

channel
optional

The item's channel (online only).

enum (online)

expirationDate
optional

Date on which the item should expire, as specified upon insertion, in ISO 8601 format. By default the value of the expirationDate is 30 days.

string

adult
optional

Set to true if the item is targeted towards adults. RECOMMENDED.

boolean

kind
optional

Identifies what kind of resource this is.

enum (content#product)

brand
optional

Brand of the item. (70 UTF8 characters max). RECOMMENDED.

string

color
optional

Color of the item.

string

googleProductCategory
optional

Google's category of the item (see Google product taxonomy). RECOMMENDED.

string

gtin
optional

Global Trade Item Number (GTIN) of the item. (14 digits max). RECOMMENDED.

string

itemGroupId
optional

Shared identifier for all variants of the same product. Case-insensitive, no quotation marks, ASCII characters, cannot match id, seller_id, (50 UTF8 characters max). RECOMMENDED.

string

material
optional

The material of which the item is made.

string

mpn
optional

Manufacturer Part Number (MPN) of the item. (70 UTF8 characters max) RECOMMENDED.

string

pattern
optional

The item's pattern (e.g. polka dots).

string

price
optional

Price of the item. (14 characters max). RECOMMENDED.

Price

salePrice
optional

Advertised sale price of the item. RECOMMENDED.

Price

salePriceEffectiveDate
optional

Date range during which the item is on sale.

string

sizes
optional

Size of the item. RECOMMENDED. Only one value is allowed. For variants with different sizes, insert a separate product for each size with the same itemGroupId value.

string array

taxes
optional

Tax information.

ProductTax array

customAttributes
optional

A list of custom (merchant-provided) attributes. This is useful for submitting attributes not explicitly exposed by the API. Declaring attributes explicitly exposed by the API using is forbidden

CustomAttribute array

identifierExists
optional

False when the item does not have unique product identifiers appropriate to its category, such as GTIN, MPN, and brand. Required according to the Unique Product Identifier Rules for all target countries except for Canada.

boolean

installment
optional

Number and amount of installments to pay for an item. Brazil only.

Installment

loyaltyPoints
optional

Loyalty points that users receive after purchasing the item. Japan only.

LoyaltyPoints

multipack
optional

The number of identical products in a merchant-defined multipack. To avoid any overflow issue, pass it as a string.

object

customLabel0
optional

Custom label 0 for custom grouping of items in a Shopping campaign.

string

customLabel1
optional

Custom label 1 for custom grouping of items in a Shopping campaign.

string

customLabel2
optional

Custom label 2 for custom grouping of items in a Shopping campaign.

string

customLabel3
optional

Custom label 3 for custom grouping of items in a Shopping campaign.

string

customLabel4
optional

Custom label 4 for custom grouping of items in a Shopping campaign.

string

isBundle
optional

Whether the item is a merchant-defined bundle. A bundle is a custom grouping of different products sold by a merchant for a single price.

boolean

mobileLink
optional

accounts.link to a mobile-optimized version of the landing page.

string

availabilityDate
optional

The day a pre-ordered product becomes available for delivery, in ISO 8601 format.

string

unitPricingMeasure
optional

The measure and dimension of an item.

ProductUnitPricingMeasure

unitPricingBaseMeasure
optional

The preference of the denominator of the unit price.

ProductUnitPricingBaseMeasure

shipping
optional

Shipping rules.

ProductShipping array

shippingLabel
optional

The shipping label of the product, used to group product in account-level shipping rules.

string

shippingLength
optional

Length of the item for shipping.

ProductShippingDimension

shippingWidth
optional

Width of the item for shipping.

ProductShippingDimension

shippingHeight
optional

Height of the item for shipping.

ProductShippingDimension

shippingWeight
optional

Weight of the item for shipping.

ProductShippingWeight

displayAdsId
optional

An identifier for an item for dynamic Retargeting campaigns.

string

displayAdsSimilarIds
optional

Advertiser-specified recommendations.

string

displayAdsTitle
optional

Title of an item for dynamic Retargeting campaigns.

string

displayAdsLink
optional

URL directly to your item's landing page for dynamic Retargeting campaigns.

string

displayAdsValue
optional

Offer margin for dynamic Retargeting campaigns.

number (double)

sellOnGoogleQuantity
optional

The quantity of the product that is available for selling on Google. Supported only for online products.

object

promotionIds
optional

The unique ID of a promotion.

string array

maxHandlingTime
optional

Maximal product handling time (in business days).

object

minHandlingTime
optional

Minimal product handling time (in business days).

object

costOfGoodsSold
optional

Cost of goods sold. Used for gross profit reporting.

Price

source
optional

The source of the offer, i.e., how the offer was created.

enum (api, crawl, feed)

includedDestinations
optional

The list of destinations to include for this target (corresponds to checked check boxes in Merchant Center). Default destinations are always included unless provided in excludedDestinations.

string array

excludedDestinations
optional

The list of destinations to exclude for this target (corresponds to unchecked check boxes in Merchant Center).

string array

adsLabels
optional

Similar to adsGrouping, but only works on CPC.

string array

adsRedirect
optional

Allows advertisers to override the item URL when the product is shown within the context of Product Ads.

string

productTypeKeys optional

Category keys of the item (formatted as in productTypes).
This information is required by RetailMedia.

string array

productTypes
optional

Categories of the item (formatted as in products data specification).

string array

ageGroup
optional

Target age group of the item.

string

availability
optional

Availability status of the item. RECOMMENDED.

string

condition
optional

Condition or state of the item.

string

gender
optional

Target gender of the item.

string

sizeSystem
optional

System in which the size is specified. Recommended for apparel items.

string

sizeType
optional

The cut of the item. Recommended for apparel items.

string

energyEfficiencyClass
optional

The energy efficiency class as defined in EU directive 2010/30/EU.

string

minEnergyEfficiencyClass
optional

The energy efficiency class as defined in EU directive 2010/30/EU.

string

maxEnergyEfficiencyClass
optional

The energy efficiency class as defined in EU directive 2010/30/EU.

string

taxCategory
optional

The tax category of the product, used to configure detailed tax nexus in account-level tax settings.

string

transitTimeLabel
optional

The transit time label of the product, used to group product in account-level transit time tables.

string

sellerId
optional

⚠️ Deprecated Field, please useexternalSellerId instead
The ID of the seller (case-sensitive and max 50 UTF-8 chars). This information is required by the Criteo Offsite Ads.

string

externalSellerId
optional

The external id of the seller (case-insensitive, no quotation marks, ASCII characters, cannot match id, itemGroupId, 50 UTF8 characters max.
This information is required by the Criteo Offsite Ads and RetailMedia.

string

externalSellerName optional

The external name of the seller (case sensitive and 200 UTF8 characters max). This information is required by the Criteo Offsite Ads and RetailMedia.

string

adsGrouping
optional

Used to group items in an arbitrary way. Only for CPA%, discouraged otherwise.

string

numberOfReviews

The number of customer reviews for the product

integer (int32)

productRating

The product rating for the product

string

badge

URL of a badge image to display on the product.

string

Filters
optional

Defines filtering criteria to apply when importing products. This object allows specifying conditions such as brand, category, or custom attributes to limit which products are processed.

Filters