Skip to main content

​
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 operationToken that can be used to track processing status. See below for response examples and result reporting.
For details on how to structure individual product objects, 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",
        "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",
        "filters": {
          "release_date": ["2025-02-15"],
          "skuPattern": ["WINTER-\\d{4}$"],
          "includeTags": ["season:winter", "collection:2025"]
        },
        "customAttributes": [
          {
            "name": "regionData",
            "value": "'123':{'Price':'41.99','Quantity':'2'},'456':{'Price':'45.99','Quantity':'1'}"
          }
        ]
      }
    },
    {
      "merchantId": "784xxx",
      "method": "insert",
      "product": {
        "id": "436715xxxx",
        "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",
        "filters": {
          "release_date": ["2025-06-20"],
          "skuPattern": ["SUMMER-\\d{4}$"],
          "includeTags": ["season:summer", "collection:2025"]
        },
        "customAttributes": [
          {
            "name": "regionData",
            "value": "'123':{'Price':'41.99','Quantity':'2'},'456':{'Price':'45.99','Quantity':'1'}"
          }
        ]
      }
    },
    {
      "merchantId": "784xxx",
      "method": "delete",
      "productId": "154956xxxx"
    }
  ]
}

​
Examples for the batch endpoint

​
202

​
Request

{
	"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

​
Request

{
  "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

​
Request

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

​
Request

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

Doesn’t apply to this particular route.

​
413

​
Request

{
  "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

​
Request

{
  "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

​
Request

{
  "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 back off algorithm.

​
503

​
Request

{
  "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 back off algorithm.

​
Examples for the report endpoint

​
200

​
Request

HTTP
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

​
Request

HTTP
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

​
Request

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

​
Request

HTTP
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

​
Request

HTTP
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

​
Request

HTTP
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

​
Request

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

​
Request

Assuming you may have exceeded your request limit. Criteo is throttling your traffic to prevent overload.
HTTP
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

​
Request

HTTP
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

​
Request

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

​
What’s next