Product Importer API

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

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

operationTokenrequired

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

filterName

Name of the filter

string

values

Values for the filter

string[]

amountoptional

The amount the buyer has to pay per month.

Price

monthsoptional

The number of installments the buyer has to pay.

Object

nameoptional

Name of loyalty points program. It is recommended to limit the name to 12 full-width characters or 24 Roman characters.

string

pointsValueoptional

The retailer’s loyalty points in absolute value.

Object

ratiooptional

The ratio of a point when converted to currency. Google assumes currency based on Merchant Center settings. If ratio is left out, it defaults to 1.0.

Number (double)

currencyoptional

The price represented as a number.

string

valueoptional

The currency of the price.

string

id

required

A unique identifier for the item. Aka Product ID.

Case-insensitive, no quotation marks, ASCII characters, cannot matchitem_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 (onlineonly).

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 matchid,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 sameitemGroupIdvalue.

string array

taxes

optional

Tax information.

ProductTaxarray

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

CustomAttributearray

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.

ProductShippingarray

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

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 toadsGrouping, 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

productTypeKeysoptional

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 useexternalSellerIdinstead

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 matchid,itemGroupId, 50 UTF8 characters max.

This information is required by the Criteo Offsite Ads and RetailMedia.

string

externalSellerNameoptional

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

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

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

valueoptional

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

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

unitoptional

The unit of the denominator.

string

valueoptional

The denominator of the unit price.

object

unitoptional

The unit of measure.

string

valueoptional

The measurement of an item.

number (double)

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)

errorsrequired

ReportDetailError

• array

productIdrequired

string

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