Product Importer payload examples
This page provides request and payload response examples for each HTTP status code, along with recommended actions.
Common batch request pattern
This section shows practical examples on how to batch insert, update, or delete products using the API.
The Product Importer (PI) API allows multiple product operations to be submitted in a single request. Each entry in the entries array represents an operation—such as adding, updating, or deleting a product—identified by the method field. Below are practical examples for typical batch request patterns.
Once your request is submitted, the API responds with an
operationTokenthat can be used to track processing status. See below for response examples and result reporting.
For details on how to structure individual
productobjects, see the examples section below.
Add Products
Add one or more new products in a single request.
{
"entries": [
{
"batchId":"",
"merchantId": "784xxx",
"method": "insert",
"product": {
"id": "123456xxxx",
"title": "New Product Title",
"price": {
"currency": "EUR",
"value": "25.99"
}
// Additional fields...
}
}
]
}
Update Products
Update attributes of existing products (e.g., price or availability).
{
"entries": [
{
"batchId":"",
"merchantId": "784xxx",
"method": "insert",
"product": {
"id": "123456xxxx",
"availability": "Out of Stock",
"salePrice": {
"currency": "EUR",
"value": "19.99"
}
}
}
]
}
Add and Update Products
Perform both insert and update operations in a single batch.
{
"entries": [
{
"batchId":"",
"merchantId": "784xxx",
"method": "insert",
"product": {
"id": "987654xxxx",
"title": "Brand New Product",
"price": {
"currency": "EUR",
"value": "29.99"
}
}
},
{
"merchantId": "784xxx",
"method": "insert",
"product": {
"id": "123456xxxx",
"title": "Updated Product Title"
}
}
]
}
Add and Delete Products
Combine inserting new products and removing old ones in the same request.
{
"entries": [
{
"batchId":"",
"merchantId": "784xxx",
"method": "insert",
"product": {
"id": "789012xxxx",
"title": "New Listing",
"price": {
"currency": "EUR",
"value": "34.99"
}
}
},
{
"merchantId": "784xxx",
"method": "delete",
"productId": "123456xxxx"
}
]
}
Update and Delete Products
{
"entries": [
{
"batchId":"",
"merchantId": "784xxx",
"method": "insert",
"product": {
"id": "654321xxxx",
"customLabel0": "Spring 2025"
}
},
{
"merchantId": "784xxx",
"method": "delete",
"productId": "111111xxxx"
}
]
}
Full mixed-method request example
The following example shows a complete request that performs both a product insert and a delete, using the full structure of a product object:
{
"entries": [
{
"batchId":"",
"merchantId": "784xxx",
"method": "insert",
"product": {
"id": "154367xxxx", // <=== new product
"title": "Title of the product",
"description": "Description of the product",
"link": "https://www.advertiser.com/300x200/myProduct",
"imageLink": "https://www.advertiser.com/300x200/myProduct.jpg",
"additionalImageLinks": [
"https://www.advertiser.com/300x200/myProduct_1.jpg",
"https://www.advertiser.com/300x200/myProduct_2.jpg"
],
"salePrice": {
"currency": "EUR",
"value": "25.99"
},
"price": {
"currency": "EUR",
"value": "25.99"
},
"gtin": "57564xx",
"mpn": "RT123xx",
"productTypes": [
"Men > Clothing > T-Shirts",
"Men > Shirts & Tops",
"Clothing > Outerwear"
],
"productTypeKeys": [
"123>456>789",
"345>567",
"21067>153"
],
"brand": "",
"itemGroupId": "875xxxxx",
"googleProductCategory": "Apparel & Accessories > Clothing > Shirts & Tops",
"availability": "In Stock",
"externalSellerId": "63563xxx",
"externalSellerName": "Seller ABC",
"productRating": "4.5",
"numberOfReviews": "10",
"customLabel0": "Spring",
"customLabel1": "Clearance",
"customLabel2": "Men",
"customAttributes": [
{
"name": "regionData",
"value": "'123':{'Price':'41.99','Quantity': '2'},'456':{'Price':'45.99','Quantity': '1'}"
},
{
"name": "filters",
"value": "size=[Large], age_group=[Adult]"
}
]
}
},
{
"merchantId": "784xxx",
"method": "insert",
"product": {
"id": "436715xxxx", // <=== existing product
"title": "Title of the product",
"description": "Description of the product",
"link": "https://www.advertiser.com/300x200/myProduct",
"imageLink": "https://www.advertiser.com/300x200/myProduct.jpg",
"additionalImageLinks": [
"https://www.advertiser.com/300x200/myProduct_1.jpg",
"https://www.advertiser.com/300x200/myProduct_2.jpg"
],
"salePrice": {
"currency": "EUR",
"value": "25.99"
},
"price": {
"currency": "EUR",
"value": "25.99"
},
"gtin": "57564xx",
"mpn": "RT123xx",
"productTypes": [
"Men > Clothing > T-Shirts",
"Men > Shirts & Tops",
"Clothing > Outerwear"
],
"productTypeKeys": [
"123>456>789",
"345>567",
"21067>153"
],
"brand": "",
"itemGroupId": "875xxxxx",
"googleProductCategory": "Apparel & Accessories > Clothing > Shirts & Tops",
"availability": "In Stock",
"externalSellerId": "63563xxx",
"externalSellerName": "Seller ABC",
"productRating": "4.5",
"numberOfReviews": "10",
"customLabel0": "Spring",
"customLabel1": "Clearance",
"customLabel2": "Men",
"customAttributes": [
{
"name": "regionData",
"value": "'123':{'Price':'41.99','Quantity': '2'},'456':{'Price':'45.99','Quantity': '1'}"
},
{
"name": "filters",
"value": "size=[Large], age_group=[Adult]"
}
]
}
},
{
"merchantId": "784xxx",
"method": "delete",
"productId": "154956xxxx"
}
]
}
Examples for the batch endpoint
batch endpoint202
202Request
{
"entries":[
{
"batchId":"",
"merchantId":"123",
"method":"insert",
"product":{
"id":"id",
"title":"myTitle",
"description":"myDescription",
"link":"https://www.advertiser.com/myProduct",
"imageLink":"https://www.advertiser.com/300x200/myProduct",
"brand":"",
"googleProductCategory":null,
"gtin":"123456789",
"price":{
"currency":"EUR",
"value":"49.99"
},
"availability":"in stock"
},
"feedId":"string"
}
]
}
Response
{
"operationToken" : "eyJhbGciOiJub25lIn0.eyJwYXJ0bmVySWQiOjEyMywib3BlcmF0aW9uSWQiOiIxNzE2YzExNC1mZThjLTRiZmYtOGFiNC0zYzM5YTQwY2M1ZGMiLCJleHAiOjE2MTYxNDIwMDJ9."
}
400
400Request
{
"entries" : [
{
}
]
}
Response
{
"errors" : [
{
"traceId" : "00000000-0000-0000-9f5b-49143a5bb0b6",
"type" : "validation",
"code" : "required-field",
"instance" : "/preview/retail-media/catalog/products/batch",
"title" : "A batch request was rejected due to one or more errors.",
"detail" : "entries.catalogId: field is required"
},
{
"traceId" : "00000000-0000-0000-9f5b-49143a5bb0b6",
"type" : "validation",
"code" : "required-field",
"instance" : "/preview/retail-media/catalog/products/batch",
"title" : "A batch request was rejected due to one or more errors.",
"detail" : "entries.method: field is required"
}
],
"warnings" : [ ]
}
Action
Please revise your request based on the error details and submit it again.
401
401Request
Assuming the user posts this payload along with an invalid bearer token.
{
"entries":[
{
"batchId":"",
"merchantId":"123",
"method":"insert",
"product":{
"id":"id",
"title":"myTitle",
"description":"myDescription",
"link":"https://www.advertiser.com/myProduct",
"imageLink":"https://www.advertiser.com/300x200/myProduct",
"brand":"",
"googleProductCategory":null,
"gtin":"123456789",
"price":{
"currency":"EUR",
"value":"49.99"
},
"availability":"in stock"
},
"feedId":"string"
}
]
}
Response
{
"errors" : [
{
"traceId" : "00000000-0000-0000-f2a6-b916ca584348",
"type" : "authentication",
"code" : "not-authenticated",
"instance" : "/preview/retail-media/catalog/products/batch",
"title" : "User is not authenticated",
"detail" : ""
}
],
"warnings" : [ ]
}
Action
Request a new token from the authentication endpoint and then retry.
403
403Request
Assuming the current authenticated user doesn't have the permission to manage merchant 123 (merchantId).
{
"entries":[
{
"batchId":"",
"merchantId":"123",
"method":"insert",
"product":{
"id":"id",
"title":"myTitle",
"description":"myDescription",
"link":"https://www.advertiser.com/myProduct",
"imageLink":"https://www.advertiser.com/300x200/myProduct",
"brand":"",
"googleProductCategory":null,
"gtin":"123456789",
"price":{
"currency":"EUR",
"value":"49.99"
},
"availability":"in stock"
},
"feedId":"string"
}
]
}
Response
{
"errors" : [
{
"traceId" : "00000000-0000-0000-89ce-d053d749483c",
"type" : "authorization",
"code" : "not-authorized",
"instance" : "/preview/retail-media/catalog/products/batch",
"title" : "User is not authorized",
"detail" : ""
}
],
"warnings" : [ ]
}
Action
Check the credentials you used to authenticate and the merchantId, then fix and then retry.
404
404Doesn't apply to this particular route.
413
413Request
{
"entries":[
{
"batchId":"",
"merchantId":"123",
"method":"insert",
"product":{
"id":"id",
"title":"myTitle",
"description":"myDescription",
"link":"https://www.advertiser.com/myProduct",
"imageLink":"https://www.advertiser.com/300x200/myProduct",
"brand":"",
"googleProductCategory":null,
"gtin":"123456789",
"price":{
"currency":"EUR",
"value":"49.99"
},
"availability":"in stock"
},
"feedId":"string"
},
{...}
]
}
Response
No body.
Action
If any text field exceeds its allowed capacity, reduce its size or decrease the batch size, then retry the request.
429
429Request
{
"entries":[
{
"batchId":"",
"merchantId":"123",
"method":"insert",
"product":{
"id":"id",
"title":"myTitle",
"description":"myDescription",
"link":"https://www.advertiser.com/myProduct",
"imageLink":"https://www.advertiser.com/300x200/myProduct",
"brand":"",
"googleProductCategory":null,
"gtin":"123456789",
"price":{
"currency":"EUR",
"value":"49.99"
},
"availability":"in stock"
},
"feedId":"string"
}
]
}
Response
{
"errors" : [
{
"traceId" : "00000000-0000-0000-f7d4-2d7504f11523",
"type" : "availability",
"code" : "too-many-requests",
"instance" : "/preview/retail-media/catalog/products/batch",
"title" : "Too many requests. Retry in 5 seconds",
"detail" : ""
}
],
"warnings" : [ ]
}
Action
Wait for the specified duration before retrying, using an exponential backoff strategy. Ensure that the number of products being sent does not exceed the default limit of 3,000 products per second per merchant.
500
500Request
{
"entries":[
{
"batchId":"",
"merchantId":"123",
"method":"insert",
"product":{
"id":"id",
"title":"myTitle",
"description":"myDescription",
"link":"https://www.advertiser.com/myProduct",
"imageLink":"https://www.advertiser.com/300x200/myProduct",
"brand":"",
"googleProductCategory":null,
"gtin":"123456789",
"price":{
"currency":"EUR",
"value":"49.99"
},
"availability":"in stock"
},
"feedId":"string"
}
]
}
Response
{
"errors" : [
{
"traceId" : "00000000-0000-0000-4ab7-8451b807408e",
"type" : "availability",
"code" : "internal-error",
"instance" : "/preview/retail-media/catalog/products/batch",
"title" : "Internal Server Error",
"detail" : ""
}
],
"warnings" : [ ]
}
Action
Retry using an exponential backoff algorithm.
503
503Request
{
"entries":[
{
"batchId":"",
"merchantId":"123",
"method":"insert",
"product":{
"id":"id",
"title":"myTitle",
"description":"myDescription",
"link":"https://www.advertiser.com/myProduct",
"imageLink":"https://www.advertiser.com/300x200/myProduct",
"brand":"",
"googleProductCategory":null,
"gtin":"123456789",
"price":{
"currency":"EUR",
"value":"49.99"
},
"availability":"in stock"
},
"feedId":"string"
}
]
}
Response
{
"errors" : [
{
"traceId" : "00000000-0000-0000-359a-9ad153aa43dd",
"type" : "availability",
"code" : "service-unavailable",
"instance" : "/preview/retail-media/catalog/products/batch",
"title" : "Service unavailable.",
"detail" : ""
}
],
"warnings" : [ ]
}
Action
Retry using an exponential backoff algorithm.
Examples for the report endpoint
report endpoint200
200Request
HTTP GET /preview/retail-media/catalog/products/batch/report/eyJhbGciOiJub25lIn0.eyJwYXJ0bmVySWQiOjEyLCJvcGVyYXRpb25JZCI6IjQyOTUyMzFmLWVmYTMtNDQzMy05NjA4LWI0ZDdkZTJjOThiNyIsImV4cCI6MTYxNjE0NTEzNX0.
Response
{
"status" : "ACCEPTED",
"importRequestTimestamp" : "1615799535383",
"numberOfProductsInTheBatch" : "1",
"numberOfProductsUpserted" : "0",
"numberOfProductsDeleted" : "0",
"numberOfProductsWithErrors" : "0",
"errorDetails" : [ ]
}
Action
The batch has been accepted, but its treatment has not started yet.
200
200Request
HTTP GET /preview/retail-media/catalog/products/batch/report/eyJhbGciOiJub25lIn0.eyJwYXJ0bmVySWQiOjEyLCJvcGVyYXRpb25JZCI6IjQyOTUyMzFmLWVmYTMtNDQzMy05NjA4LWI0ZDdkZTJjOThiNyIsImV4cCI6MTYxNjE0NTEzNX0.
Response
{
"status" : "VALIDATED",
"importRequestTimestamp" : "1615799535032",
"numberOfProductsInTheBatch" : "2",
"numberOfProductsUpserted" : "2",
"numberOfProductsDeleted" : "0",
"numberOfProductsWithErrors" : "0",
"errorDetails" : [ ]
}
Action
The batch has been fully validated without any error.
200
200Request
- Assuming a batch of one product has been submitted successfully,
- Assuming that a transformation occurred on the
imageUrl, such as a prefix being added to the original URL, which could lead to potential overflow.
HTTP GET /preview/retail-media/catalog/products/batch/report/eyJhbGciOiJub25lIn0.eyJwYXJ0bmVySWQiOjEyLCJvcGVyYXRpb25JZCI6IjQyOTUyMzFmLWVmYTMtNDQzMy05NjA4LWI0ZDdkZTJjOThiNyIsImV4cCI6MTYxNjE0NTEzNX0.
Response
{
"status":"FAILED",
"importRequestTimestamp":"1615818496157",
"numberOfProductsInTheBatch":"1",
"numberOfProductsUpserted":"0",
"numberOfProductsDeleted":"0",
"numberOfProductsWithErrors":"1",
"errorDetails":[
{
"productId":"test-v3-1615818478409",
"errors":[
{
"type":"OverlargeBigImage",
"message":"{\"Length\":1042}",
"isServerRelated":false
}
]
}
]
}
Action
Since Criteo applies transformations to align incoming data with its product schema, transformation failures may occur. These issues can typically be resolved by adjusting either the product definition or the transformation process.
400
400Request
HTTP GET /preview/retail-media/catalog/products/batch/report/invalidToken
Response
{
"errors" : [
{
"traceId" : "00000000-0000-0000-1032-0fa670f40edf",
"type" : "validation",
"code" : "catalog-operation-token-is-malformed",
"instance" : "/preview/retail-media/catalog/products/batch/report/invalidToken",
"title" : "The operationToken is malformed.",
"detail" : ""
}
],
"warnings" : [ ]
}
Action
Fix the indicated error, then retry.
403
403Request
HTTP GET /preview/retail-media/catalog/products/batch/report/eyJhbGciOiJub25lIn0.eyJwYXJ0bmVySWQiOjEyLCJvcGVyYXRpb25JZCI6ImM2NjliZmM1LTYzMWEtNDE3Mi05ODhiLTM0OTdlZDg3OThmZiIsImV4cCI6MTYxNjE0NTEzNX0.
Response
{
"errors" : [
{
"traceId" : "00000000-0000-0000-6864-75f39046f226",
"type" : "authorization",
"code" : "not-authorized",
"instance" : "/preview/retail-media/catalog/products/batch/report/eyJhbGciOiJub25lIn0.eyJwYXJ0bmVySWQiOjEsIm9wZXJhdGlvbklkIjoib3BlcmF0aW9uX2lkX3Rlc3QiLCJleHAiOjE2MTYwNjEwMTN9.",
"title" : "User is not authorized",
"detail" : ""
}
],
"warnings" : [ ]
}
Action
Verify that the credentials used for this operation are authorized to access the partner's services.
404
404Request
HTTP GET /preview/retail-media/catalog/products/batch/report/eyJhbGciOiJub25lIn0.eyJwYXJ0bmVySWQiOjEyLCJvcGVyYXRpb25JZCI6ImM2NjliZmM1LTYzMWEtNDE3Mi05ODhiLTM0OTdlZDg3OThmZiIsImV4cCI6MTYxNjE0NTEzNX0.
Response
{
"errors" : [
{
"traceId" : "00000000-0000-0000-6d24-98c37d815352",
"type" : "validation",
"code" : "catalog-operation-not-found",
"instance" : "/preview/retail-media/catalog/products/batch/report/eyJhbGciOiJub25lIn0.eyJwYXJ0bmVySWQiOjEyLCJvcGVyYXRpb25JZCI6ImM2NjliZmM1LTYzMWEtNDE3Mi05ODhiLTM0OTdlZDg3OThmZiIsImV4cCI6MTYxNjE0NTEzNX0.",
"title" : "Operation 'c669bfc5-631a-4172-988b-3497ed8798ff' not found.",
"detail" : ""
}
],
"warnings" : [ ]
}
Action
The requested operation could not be found, possibly due to a significant service disruption. Criteo recommends resubmitting the entire batch to ensure successful processing.
413
413Request
Corrupted tokens, particularly those with overly large payloads, may lead to processing errors.
Response
No body.
Action
Ensure the token is well-formed and that its payload does not exceed the maximum allowed size. Generate a new token if necessary.
429
429Request
Assuming you may have exceeded your request limit. Criteo is throttling your traffic to prevent overload.
HTTP GET /preview/retail-media/catalog/products/batch/report/eyJhbGciOiJub25lIn0.eyJwYXJ0bmVySWQiOjEyLCJvcGVyYXRpb25JZCI6ImM2NjliZmM1LTYzMWEtNDE3Mi05ODhiLTM0OTdlZDg3OThmZiIsImV4cCI6MTYxNjE0NTEzNX0.
Response
{
"errors" : [
{
"traceId" : "00000000-0000-0000-f7d4-2d7504f11524",
"type" : "availability",
"code" : "too-many-requests",
"instance" : "/preview/retail-media/catalog/products/batch/report/eyJhbGciOiJub25lIn0.eyJwYXJ0bmVySWQiOjEyLCJvcGVyYXRpb25JZCI6ImM2NjliZmM1LTYzMWEtNDE3Mi05ODhiLTM0OTdlZDg3OThmZiIsImV4cCI6MTYxNjE0NTEzNX0.",
"title" : "Too many requests. Retry in 5 seconds",
"detail" : ""
}
],
"warnings" : [ ]
}
Action
Wait for the specified duration before retrying, using an exponential backoff strategy. Since the average time to generate a report for 1,000 products is typically under 3 seconds, Criteo recommends initiating polling after 3 seconds and then applying exponential backoff for subsequent retries.
500
500Request
HTTP GET /preview/retail-media/catalog/products/batch/report/eyJhbGciOiJub25lIn0.eyJwYXJ0bmVySWQiOjEyLCJvcGVyYXRpb25JZCI6ImM2NjliZmM1LTYzMWEtNDE3Mi05ODhiLTM0OTdlZDg3OThmZiIsImV4cCI6MTYxNjE0NTEzNX0.
Response
{
"errors" : [
{
"traceId" : "00000000-0000-0000-4ab7-8451b807408e",
"type" : "availability",
"code" : "internal-error",
"instance" : "/preview/retail-media/catalog/products/batch/report/eyJhbGciOiJub25lIn0.eyJwYXJ0bmVySWQiOjEyLCJvcGVyYXRpb25JZCI6ImM2NjliZmM1LTYzMWEtNDE3Mi05ODhiLTM0OTdlZDg3OThmZiIsImV4cCI6MTYxNjE0NTEzNX0.",
"title" : "Internal Server Error",
"detail" : ""
}
],
"warnings" : [ ]
}
Action
Retry using an exponential backoff algorithm.
503
503Request
HTTP GET /preview/retail-media/catalog/products/batch/report/eyJhbGciOiJub25lIn0.eyJwYXJ0bmVySWQiOjEyLCJvcGVyYXRpb25JZCI6ImM2NjliZmM1LTYzMWEtNDE3Mi05ODhiLTM0OTdlZDg3OThmZiIsImV4cCI6MTYxNjE0NTEzNX0.
Response
{
"errors" : [
{
"traceId" : "00000000-0000-0000-359a-9ad153aa43dd",
"type" : "availability",
"code" : "service-unavailable",
"instance" : "/preview/retail-media/catalog/products/batch/report/eyJhbGciOiJub25lIn0.eyJwYXJ0bmVySWQiOjEyLCJvcGVyYXRpb25JZCI6ImM2NjliZmM1LTYzMWEtNDE3Mi05ODhiLTM0OTdlZDg3OThmZiIsImV4cCI6MTYxNjE0NTEzNX0.",
"title" : "Service unavailable.",
"detail" : ""
}
],
"warnings" : [ ]
}
Action
Retry using an exponential backoff algorithm.
Updated 7 days ago
What’s Next