> ## Documentation Index > Fetch the complete documentation index at: https://developers.criteo.com/llms.txt > Use this file to discover all available pages before exploring further. # Product Importer API ## **Overview** This document outlines the Criteo Product Catalog API, detailing the existing methods and their data representation of the request body. ## **Usage workflow** Find below a simplified diagram with the workflow of API calls to post one or more products to Criteo’s database. piv3.png * **Authenticate** your app by calling the **/oauth2/token** endpoint (please see the [dedicated guide for Authentication](/marketing-solutions/v2026-preview/docs/authentication) ) * Criteo API will authenticate and authorize your app, and return you an **access token** to be used in your following calls; * **Post your products’ updates** in a JSON payload, calling the **POST /preview/catalog/products/batch** resource * Criteo API will then perform the requested update in the indicated products, which may take up to an hour. * **Get a report** on the status of your import **GET /preview/catalog/products/batch/report/\{operation-token}** *** ## **Best Practices** * Avoid daily updates of all of your products. Instead, only update products whose data has actually changed, the API cannot be used as feed ingestion. * To have up-to-date data, send updates of your products as soon as the products change, do not wait for several updates to group them. * Do not send multiple updates of the same product in the same batch, the batch will be rejected and you will receive an error. * Do not send updates for unchanged products. Be sure to only send requests for new, updated, or deleted products, unless the products are going to expire. * Make sure to update the products before they expire, the lifespan of the products is **30 days** after their last update, if you want to change their lifespan, you can use the **expirationDate** field specifying a date expiry, this date may be up to one year in the future. * Send a deleted batch as soon as the product is removed from your store, do not rely on its expiration date, otherwise, you risk displaying the product when it is no longer available in your store. * Use the same value for the Item Group ID **itemGroupId** 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***). * The **id** and **itemGroupId** fields must be different, use the **id** field to uniquely identify a single product and use **itemGroupId** to group multiple products as variants. * Don't mix up **itemGroupId** and **id** attributes, The **itemGroupId** must be chosen outside of the **id** range. If a product has the same **id** as an existing **itemGroupId** or vice versa, the behavior is undefined and updates on your products may be ignored. * Make sure to provide **itemGroupId** information in addition to the **id** when deleting a product variant to avoid any inconsistencies. *** ## **List of Methods**

Method

HTTP Request

Description

  • \_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

*** ## **Rate limitations** * 1000 products per batch * One partner\_id per request * Two updates or more of one product on the same batch is not allowed *** ## **Support** For more information about this API reach out to your account technical contact in Criteo. *** ## **Authenticate** Get detailed information on API authentication in [Authentication guide](/marketing-solutions/v2026-preview/docs/authentication) ### **Authentication**

Type

Endpoint

Objective

Parameters

Remarks

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

You will need this token as an authorization for every other endpoint, which is in the form of a bearer token. *** ## **Batch** **POST /preview/catalog/products/batch** ### **Description** Used to publish a batch of operations to insert, update and deletes products. The batch is processed asynchronously. The response provides an operationToken which can be used to track the status of the report of the operation. ### **Parameters**

Type

Name

Description

Schema

Body

ProductsCustomBatchRequest

*optional*

Defines a batch of operations

ProductsCustomBatchRequest

### **Responses**

HTTP code

Description

Schema

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="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="authorization", code="not-authorized")]

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

### **Produces** * application/json *** ## **Report** **GET /preview/catalog/products/batch/report/\{operation-token}** ### **Description** Get the report of an asynchronous batch operation previously requested ### **Parameters**

Type

Name

Description

Schema

Path

operation-token

*required*

The token returned by the batch endpoint

String

### **Responses**

HTTP Code

Description

Schema

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="authorization", code="not-authorized")]

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

### **Produces** * application/json *** ## **Definitions** ***BatchAcceptedResponse***\ A batch was accepted. The report can be accessed using the reporting endpoint.

Name

Schema

operationToken *required*

String

***CustomAttribute***\ Defines a custom attribute of a product.

Name

Description

Schema

name

*required*

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

String

value

*required*

The value of the attribute.

String

***Error***\ Error descriptor.

Name

Description

Schema

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

***FailResponse***\ Error server response.

Name

Description

Schema

errors

*required*

List of errors

\< Error \> array

warnings

*optional*

List of warnings

\< Warning > array

***Installment***\ Defines the installment of a product.

Name

Description

Schema

amount *optional*

The amount the buyer has to pay per month.

Price

months *optional*

The number of installments the buyer has to pay.

Object

***LoyaltyPoints***\ Defines how a client earns loyalty points after buying this product.

Name

Description

Schema

name *optional*

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

String

pointsValue *optional*

The retailer’s loyalty points in absolute value.

Object

ratio *optional*

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)

***Price***\ Defines a price.

Name

Description

Schema

currency *optional*

The price represented as a number.

String

value *optional*

The currency of the price.

String

***Product***\ Defines a product to be inserted or updated.

name

description

schema

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 use externalSellerId 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

***ProductShipping***\ Defines the shipping information of a product.

Name

Description

Schema

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 shipping rate applies to, represented by a postal code, a postal code prefix followed by a \* wildcard, a range between two postal codes or two postal code prefixes of equal length.

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

***ProductShippingDimension***\ Defines the shipping dimension of a product.

Name

Description

Schema

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)

***ProductShippingWeight***\ Defines the shipping weight of a product.

Name

Description

Schema

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)

***ProductTax***\ Defines the tax information of a product.

Name

Description

Schema

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

***ProductUnitPricingBaseMeasure***\ Defines a measurement.

Name

Description

Schema

unit *optional*

The unit of the denominator.

string

value *optional*

The denominator of the unit price.

object

***ProductUnitPricingMeasure***\ Defines a measurement.

Name

Description

Schema

unit *optional*

The unit of measure.

string

value *optional*

The measurement of an item.

number (double)

***ProductsCustomBatchRequest***

Name

Description

Schema

entries *required*

The request entries to be processed in the batch.

\< ProductsCustomBatchRequestEntry \> array

***ProductsCustomBatchRequestEntry***\ A batch entry encoding a single non-batch products request.

Name

Description

Schema

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

***ReportDetailError***\ An error on a batch operation.

Name

Schema

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)

***ReportDetailErrors***\ A list of errors on a batch operation.

Name

Schema

errors *required*

\< ReportDetailError \> array

productId *required*

string

***ReportOkResponse***\ The report on a given operationToken is ready.

Name

Description

Schema

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)

For more information about the semantics of each field, please refer to Criteo Product Feed Specification. For more information about this API reach out to your account technical contact in Criteo.