Product Importer Examples

Examples for the `batch` endpoint

Below you will find request and response examples for each Http response status as well as suggested actions.

`202`

Request

Example Request

{
	"entries":[
		{
			"batchId":0,
			"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

Example Response

{
  "operationToken" : "eyJhbGciOiJub25lIn0.eyJwYXJ0bmVySWQiOjEyMywib3BlcmF0aW9uSWQiOiIxNzE2YzExNC1mZThjLTRiZmYtOGFiNC0zYzM5YTQwY2M1ZGMiLCJleHAiOjE2MTYxNDIwMDJ9."
}

`400`

Request

Example Request

{
  "entries" : [ ]
}

Response

Example Response

{
  "errors" : [
    {
      "traceId" : "00000000-0000-0000-ab24-e9383cbc939e",
      "type" : "validation",
      "code" : "batch-empty",
      "instance" : "/preview/catalog/products/batch",
      "title" : "A batch request was rejected due to one or more errors.",
      "detail" : "The batch is empty."
    }
  ],
    "warnings" : [ ]
}

Action
Given the error’s detail, fix your request and then re submit.

`400`

Request

Example Request

{
  "entries" : [
    {
      "batchId" : "123"
    }
  ]
}

Response

Example Response

{
  "errors" : [
    {
      "traceId" : "00000000-0000-0000-9f5b-49143a5bb0b6",
      "type" : "validation",
      "code" : "required-field",
      "instance" : "/preview/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/catalog/products/batch",
      "title" : "A batch request was rejected due to one or more errors.",
      "detail" : "entries.method: field is required"
    }
  ],
    "warnings" : [ ]
}

Action
Given the error’s detail, fix your request and then re submit.

`401`

Request
Assuming the user post this payload along with an invalid bearer token

Example Request

{
  "entries":[
    {
      "batchId":0,
      "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

Example Response

{
  "errors" : [
    {
      "traceId" : "00000000-0000-0000-f2a6-b916ca584348",
      "type" : "authentication",
      "code" : "not-authenticated",
      "instance" : "/preview/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 (aka partner) 123

Example Request

{
  "entries":[
    {
      "batchId":0,
      "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

Example Response

{
  "errors" : [
    {
      "traceId" : "00000000-0000-0000-89ce-d053d749483c",
      "type" : "authorization",
      "code" : "not-authorized",
      "instance" : "/preview/catalog/products/batch",
      "title" : "User is not authorized",
      "detail" : ""
    }
  ],
  "warnings" : [ ]
}

Action
Check the credentials you used to authenticate, check the merchantId you used, fix and the retry.

`404`

Doesn’t apply to this particular route.

`413`

Request

Example Request

{
  "entries":[
    {
      "batchId":0,
      "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
Reduce size of text field if any is over the field capacity or reduce the size of the batch, and then retry.

`429`

Request

Example Request

{
  "entries":[
    {
      "batchId":0,
      "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

Example Response

{
"errors" : [
{
"traceId" : "00000000-0000-0000-f7d4-2d7504f11523",
"type" : "availability",
"code" : "too-many-requests",
"instance" : "/preview/catalog/products/batch",
"title" : "Too many requests. Retry in 5 seconds",
"detail" : ""
}
],
"warnings" : [ ]
}

Action
Wait for the time provided before retrying using an exponential backoff algorithm.
Consider checking the number of products you’re trying to send. The default limit is set to 3000 products / s per merchant.

`500`

Request

Example Request

{
  "entries":[
    {
      "batchId":0,
      "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

Example Response

{
  "errors" : [
    {
      "traceId" : "00000000-0000-0000-4ab7-8451b807408e",
      "type" : "availability",
      "code" : "internal-error",
      "instance" : "/preview/catalog/products/batch",
      "title" : "Internal Server Error",
      "detail" : ""
    }
  ],
  "warnings" : [ ]
}

Action
Retry using a exponential backoff algorithm.

`503`

Request

Example Request

{
  "entries":[
    {
      "batchId":0,
      "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

Example Response

{
  "errors" : [
    {
      "traceId" : "00000000-0000-0000-359a-9ad153aa43dd",
      "type" : "availability",
      "code" : "service-unavailable",
      "instance" : "/preview/catalog/products/batch",
      "title" : "Service unavailable.",
      "detail" : ""
    }
  ],
    "warnings" : [ ]
}

Action
Retry using a exponential backoff algorithm.

Examples for the `report` endpoint

`200`

Request

Example Request

HTTP GET /preview/catalog/products/batch/report/eyJhbGciOiJub25lIn0.eyJwYXJ0bmVySWQiOjEyLCJvcGVyYXRpb25JZCI6IjQyOTUyMzFmLWVmYTMtNDQzMy05NjA4LWI0ZDdkZTJjOThiNyIsImV4cCI6MTYxNjE0NTEzNX0.

Response

Example Response

{
  "status" : "ACCEPTED",
  "importRequestTimestamp" : "1615799535383",
  "numberOfProductsInTheBatch" : "1",
  "numberOfProductsUpserted" : "0",
  "numberOfProductsDeleted" : "0",
  "numberOfProductsWithErrors" : "0",
  "errorDetails" : [ ]
}

Action
The batch has been accepted, its treatment hasn’t started yet.

`200`

Request

Example Request

HTTP GET /preview/catalog/products/batch/report/eyJhbGciOiJub25lIn0.eyJwYXJ0bmVySWQiOjEyLCJvcGVyYXRpb25JZCI6IjQyOTUyMzFmLWVmYTMtNDQzMy05NjA4LWI0ZDdkZTJjOThiNyIsImV4cCI6MTYxNjE0NTEzNX0.

Response

Example 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 succesfully
Assuming a transformation happens on the imageUrl such as text is prepended to the originalImage Url leading to some possible overflow.

Example Request

HTTP GET /preview/catalog/products/batch/report/eyJhbGciOiJub25lIn0.eyJwYXJ0bmVySWQiOjEyLCJvcGVyYXRpb25JZCI6IjQyOTUyMzFmLWVmYTMtNDQzMy05NjA4LWI0ZDdkZTJjOThiNyIsImV4cCI6MTYxNjE0NTEzNX0.

Response

Example 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
Because Criteo apply some transformation to adapt the incoming format to Criteo product definition, it may happen that Criteo fails to transform a product.
Such issues can be fixed by either changing the product definition or the transformation procedure.

`400`

Request

Example Request

HTTP GET /preview/catalog/products/batch/report/invalidToken

Response

Example Response

{
  "errors" : [
    {
      "traceId" : "00000000-0000-0000-1032-0fa670f40edf",
      "type" : "validation",
      "code" : "catalog-operation-token-is-malformed",
      "instance" : "/preview/catalog/products/batch/report/invalidToken",
      "title" : "The operationToken is malformed.",
      "detail" : ""
    }
  ],
    "warnings" : [ ]
}

Action
Fix then retry.

`403`

Request

Example Request

HTTP GET /preview/catalog/products/batch/report/eyJhbGciOiJub25lIn0.eyJwYXJ0bmVySWQiOjEyLCJvcGVyYXRpb25JZCI6ImM2NjliZmM1LTYzMWEtNDE3Mi05ODhiLTM0OTdlZDg3OThmZiIsImV4cCI6MTYxNjE0NTEzNX0.

Response

Example Response

{
  "errors" : [
    {
      "traceId" : "00000000-0000-0000-6864-75f39046f226",
      "type" : "authorization",
      "code" : "not-authorized",
      "instance" : "/preview/catalog/products/batch/report/eyJhbGciOiJub25lIn0.eyJwYXJ0bmVySWQiOjEsIm9wZXJhdGlvbklkIjoib3BlcmF0aW9uX2lkX3Rlc3QiLCJleHAiOjE2MTYwNjEwMTN9.",
      "title" : "User is not authorized",
      "detail" : ""
    }
  ],
    "warnings" : [ ]
}

Action
Check the credentials you used to access this operation is authorized to access this partner’s operation.

`404`

Request

Example Request

HTTP GET /preview/catalog/products/batch/report/eyJhbGciOiJub25lIn0.eyJwYXJ0bmVySWQiOjEyLCJvcGVyYXRpb25JZCI6ImM2NjliZmM1LTYzMWEtNDE3Mi05ODhiLTM0OTdlZDg3OThmZiIsImV4cCI6MTYxNjE0NTEzNX0.

Response

Example Response

{
  "errors" : [
    {
      "traceId" : "00000000-0000-0000-6d24-98c37d815352",
      "type" : "validation",
      "code" : "catalog-operation-not-found",
      "instance" : "/preview/catalog/products/batch/report/eyJhbGciOiJub25lIn0.eyJwYXJ0bmVySWQiOjEyLCJvcGVyYXRpb25JZCI6ImM2NjliZmM1LTYzMWEtNDE3Mi05ODhiLTM0OTdlZDg3OThmZiIsImV4cCI6MTYxNjE0NTEzNX0.",
      "title" : "Operation 'c669bfc5-631a-4172-988b-3497ed8798ff' not found.",
      "detail" : ""
    }
  ],
    "warnings" : [ ]
}

Action
This operation hasn’t been found. This could happen in case of a severe unavailability.
Criteo recommends to resubmit the entire batch.

`413`

Request
Any corrupted token such as the payload is really too heavy.
Response
No body.
Action
Fix.

`429`

Request
Assuming you’re sending too many requests and hit your limit.
Criteo throttles your requests.

Example Request

HTTP GET /preview/catalog/products/batch/report/eyJhbGciOiJub25lIn0.eyJwYXJ0bmVySWQiOjEyLCJvcGVyYXRpb25JZCI6ImM2NjliZmM1LTYzMWEtNDE3Mi05ODhiLTM0OTdlZDg3OThmZiIsImV4cCI6MTYxNjE0NTEzNX0.

Response

Example Response

{
  "errors" : [
    {
      "traceId" : "00000000-0000-0000-f7d4-2d7504f11524",
      "type" : "availability",
      "code" : "too-many-requests",
      "instance" : "/preview/catalog/products/batch/report/eyJhbGciOiJub25lIn0.eyJwYXJ0bmVySWQiOjEyLCJvcGVyYXRpb25JZCI6ImM2NjliZmM1LTYzMWEtNDE3Mi05ODhiLTM0OTdlZDg3OThmZiIsImV4cCI6MTYxNjE0NTEzNX0.",
      "title" : "Too many requests. Retry in 5 seconds",
      "detail" : ""
    }
  ],
    "warnings" : [ ]
}

Action
Wait for the time provided before retrying using an exponential backoff algorithm.
As the average time to get a report of 1000 products should be less than 3 seconds, Criteo recommends to start polling after 3 seconds and then retry using the exponential backoff algorithm.

`500`

Request

Example Request

HTTP GET /preview/catalog/products/batch/report/eyJhbGciOiJub25lIn0.eyJwYXJ0bmVySWQiOjEyLCJvcGVyYXRpb25JZCI6ImM2NjliZmM1LTYzMWEtNDE3Mi05ODhiLTM0OTdlZDg3OThmZiIsImV4cCI6MTYxNjE0NTEzNX0.

Response

Example Response

{
  "errors" : [
    {
      "traceId" : "00000000-0000-0000-4ab7-8451b807408e",
      "type" : "availability",
      "code" : "internal-error",
      "instance" : "/preview/catalog/products/batch/report/eyJhbGciOiJub25lIn0.eyJwYXJ0bmVySWQiOjEyLCJvcGVyYXRpb25JZCI6ImM2NjliZmM1LTYzMWEtNDE3Mi05ODhiLTM0OTdlZDg3OThmZiIsImV4cCI6MTYxNjE0NTEzNX0.",
      "title" : "Internal Server Error",
      "detail" : ""
    }
  ],
  "warnings" : [ ]
}

Action
Retry using a exponential backoff algorithm.

`503`

Request

Example Request

HTTP GET /preview/catalog/products/batch/report/eyJhbGciOiJub25lIn0.eyJwYXJ0bmVySWQiOjEyLCJvcGVyYXRpb25JZCI6ImM2NjliZmM1LTYzMWEtNDE3Mi05ODhiLTM0OTdlZDg3OThmZiIsImV4cCI6MTYxNjE0NTEzNX0.

Response

Example Response

{
  "errors" : [
    {
      "traceId" : "00000000-0000-0000-359a-9ad153aa43dd",
      "type" : "availability",
      "code" : "service-unavailable",
      "instance" : "/preview/catalog/products/batch/report/eyJhbGciOiJub25lIn0.eyJwYXJ0bmVySWQiOjEyLCJvcGVyYXRpb25JZCI6ImM2NjliZmM1LTYzMWEtNDE3Mi05ODhiLTM0OTdlZDg3OThmZiIsImV4cCI6MTYxNjE0NTEzNX0.",
      "title" : "Service unavailable.",
      "detail" : ""
    }
  ],
    "warnings" : [ ]
}

Action
Retry using a exponential backoff algorithm.

​Examples for the batch endpoint

​202

​400

​400

​401

​403

​404

​413

​429

​500

​503

​Examples for the report endpoint

​200

​200

​200

​400

​403

​404

​413

​429

​500

​503

Examples for the `batch` endpoint

`202`

`400`

`400`

`401`

`403`

`404`

`413`

`429`

`500`

`503`

Examples for the `report` endpoint

`200`

`200`

`200`

`400`

`403`

`404`

`413`

`429`

`500`

`503`