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/retail-media/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/retail-media/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

POST

/preview/retail-media/catalog/products/batch

ProductsCustomBatchRequest

• optional_ - Defines a batch of operations

ProductsCustomBatchRequest

202

Batch accepted. The status of the operation can be tracked using the report endpoint and the operationToken.

BatchAcceptedResponse

400

Bad Request. Allowed error types and errors:

• {"type": "validation", "code": "required-field"}
• {"type": "validation", "code": "json-format"}

FailResponse

401

Unauthorized. Allowed error types and errors:

• {"type": "authentication", "code": "not-authenticated"}

FailResponse

403

Forbidden. Allowed error types and errors:

• {"type": "authentication", "code": "not-authenticated"}

FailResponse

413

Request too long

No Content

429

Too Many Requests. Allowed error types and errors:

• {"type": "availability", "code": "too-many-requests"}

FailResponse

500

Internal Server Error. Allowed error types and errors:

• {"type": "availability", "code": "internal-error"}

FailResponse

503

Service Unavailable. Allowed error types and errors:

• {"type": "availability", "code": "service-unavailable"}

FailResponse

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.

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. (max 1000 UTF-8 chars).

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.

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. 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. RECOMMENDED.

string

itemGroupId
optional

Shared identifier for all variants of the same product. RECOMMENDED.

string

material
optional

The material of which the item is made.

string

mpn
optional

Manufacturer Part Number (MPN) of the item. RECOMMENDED.

string

pattern
optional

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

string

price
optional

Price of the item. 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 sensitive and 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 50 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

country optional

The CLDR territory code of the country to which an item will ship.

string

locationGroupName
optional

The location where the shipping is applicable, represented by a location group name.

string

locationId
optional

The numeric ID of a location that the shipping rate applies to as defined in the AdWords API.

object

postalCode
optional

The postal code range that the tax rate applies to, represented by a ZIP code, a ZIP code prefix using * (wildcard), a range between two ZIP codes or two ZIP code prefixes of equal length. Examples: 94114, 94*, 94002-95460, 94*-95*.

string

price
optional

Fixed shipping price, represented as a number.

Price

region
optional

The geographic region to which a shipping rate applies.

string

service
optional

A free-form description of the service class or delivery speed.

string

• *unit** optional

The unit of value.

string

• *value** optional

The dimension of the product used to calculate the shipping cost of the item.

number
(double)

• *unit** optional

The unit of value.

string

• *value** optional

The weight of the product used to calculate the shipping cost of the item.

number
(double)

country optional

The country within which the item is taxed, specified as a CLDR territory code.

string

locationId
optional

The numeric ID of a location that the tax rate applies to as defined in the AdWords API.

object

postalCode
optional

The postal code range that the tax rate applies to, represented by a ZIP code, a ZIP code prefix using * (wildcard), a range between two ZIP codes or two ZIP code prefixes of equal length. Examples: 94114, 94*, 94002-95460, 94*-95*.

string

rate
optional

The percentage of tax rate that applies to the item price.

number
(double)

region
optional

The geographic region to which the tax rate applies.

string

taxShip
optional

Set to true if tax is charged on shipping.

boolean

entries required

The request entries to be processed in the batch.

ProductsCustomBatchRequestEntry - array

batchId optional

An entry ID, unique within the batch request.

integer (int64)

feedId
optional

Not used by Criteo.

string

merchantId
required

The ID of the managing account. Criteo: the partnerId.

integer (int32)

method
required

The method of the batch entry.

enum (delete, insert)

product
optional

The product to insert. Only required if the method is insert.

Product

productId
optional

The Product ID to delete. Only defined if the method is delete.

string

isServerRelated required

boolean

message
optional

string

type
required

enum (UnknownError, InvalidBigImageUrl, InvalidProductId, InvalidProductUrl, InvalidSmallImageUrl, JsonParsingIssue, MissingID, MissingImages, MissingName, MissingURL, NonAsciiId, OverlargeBigImage, OverlargeID, OverlargeSmallImage, OverlargeURL, ConfigurationError)

errorDetails required

The list of errors with details.

ReportDetailErrors - array

importRequestTimestamp
required

The date when the original batch request was sent.

integer (int64)

numberOfProductsDeleted
required

The number of products deleted.

integer (int32)

numberOfProductsInTheBatch
required

The number of products present in the batch.

integer (int32)

numberOfProductsUpserted
required

The number of products upserted.

integer (int32)

numberOfProductsWithErrors
required

The number of products with errors.

integer (int32)

status
required

The status of the operation. The operation is completed when the status is one of: VALIDATED, VALIDATED_WITH_ERRORS, FAILED)

enum (ACCEPTED, IN_PROGRESS, VALIDATED, VALIDATED_WITH_ERRORS, FAILED)

GET

/preview/retail-media/catalog/products/batch/report/{operation-token}

operation-token

• required_ - The token returned by the batch endpoint

string

200

The report object

ReportOkResponse

400

Bad Request. Allowed error types and errors:

• {"type": "validation", "code": "catalog-operation-token-is-malformed"}
• {"type": "validation", "code": "catalog-operation-report-is-expired"}

FailResponse

401

Unauthorized. Allowed error types and errors:

• {"type": "authentication", "code": "not-authenticated"}

FailResponse

403

Forbidden. Allowed error types and errors:

• {"type": "authentication", "code": "not-authenticated"}

FailResponse

404

Not Found. Allowed error types and errors:

• {"type": "validation", "code": "catalog-operation-not-found"}

FailResponse

429

Too Many Requests

No Content

500

Internal Server Error. Allowed error types and errors:

• {"type": "availability", "code": "internal-error"}

FailResponse

503

Service Unavailable. Allowed error types and errors:

• {"type": "availability", "code": "service-unavailable"}

FailResponse