Skip to main content
Generate and download a copy of retailer’s inventory

​
Endpoints

MethodEndpointDescription
POST/accounts/{accountId}/catalogsCreate a catalog request to generate a new catalog for Brand account
POST/accounts/{accountId}/catalogs/sellersCreate a catalog request to generate a new catalog for Seller account
GET/catalogs/{catalogId}/statusRetrieve the status of a specific catalog request.
GET/catalogs/{catalogId}/outputDownload the output of a specific catalog once it’s ready.

​
Catalog Creation Request Attributes (for Brand accounts)

​
format
Data Type: stringDescription: Format of the catalog data returnedValues: json-newline
​
brandIDFilter
Data Type: stringDescription: Brand(s) ids used to filter down catalog results based on specified brandsValues: int64

​
Catalog Creation Request Attributes (for Seller accounts)

​
retailerId
required
Data Type: stringValues: int64Description: Retailer id(s) carrying the product
​
sellerId
required
Data Type: stringValues: -Description: Seller id(s) in respective retailers’ catalogs, used to filter down catalog items

​
Catalog Status Response Attributes

​
id
Data Type: stringValues: int64Description: ID of the catalog creation status request
​
type
Data Type: stringValues: RetailMediaCatalogStatusDescription: Type definition of the following attributes structure
​
status
Data Type: stringValues: enum with possible values: pending, success, failure, expired, unknownDescription: Status of the catalog creation request
​
currency
Data Type: stringValues: USD, EUR, etcDescription: ISO-4217 currency of the items in the respective catalog
​
rowCount
Data Type: integerValues: int32Description: Number of products contained in the catalog (available when creation reaches success status)
​
fileSizeBytes
Data Type: integerValues: int32Description: Size of catalog, in bytes (available when creation reaches success status)
​
md5Checksum
Data Type: stringValues: 32-char alpha-numeric stringsDescription: MD5 checksum of catalog’s content (available when creation reaches success status)
​
createdAt
Data Type: timestampValues: ISO-8601Description: Timestamp of the creation
​
message
Data Type: stringValues: -Description: Optional informative message, for developer consumption

​
Catalog Output Response Attributes

​
id
Data Type: stringValues: 500 char limitDescription: Retailer product ID, established by the retailer
​
name
Data Type: stringValues: 1000 char limitDescription: Retailer product name
​
category
Data Type: stringValues: 1000 char limitDescription: Retailer product category
​
brandName
Data Type: stringValues: 120 char limitDescription: Brand name of the product; names are standardized across retailers
​
retailerId
Data Type: stringValues: int64Description: Retailer ID carrying the product
​
retailerName
Data Type: stringValues: 100 char limitDescription: Retailer name carrying the product
​
price
Data Type: numberValues: -Description: Retailer product price in USD
​
isInStock
Data Type: booleanValues: true, falseDescription: Whether or not the product is in stock
​
minBid
Data Type: numberValues: greater than 0Description: Minimum Cost-Per-Click (CPC) an advertiser must bid for the product, established by the retailer; any line item with this product must have targetBid meet this value
​
gtin
Data Type: stringValues: -Description: Global Trade Item Number (GTIN), if available; also known as European Article Number (EAN) or Universal Product Code (UPC)
​
mpn
Data Type: stringValues: -Description: Manufacturer Part Number (MPN), if available
​
imageUrl
Data Type: stringValues: -Description: An http image URL provided by the retailer
​
updatedAt
Data Type: timestampValues: ISO-8601Description: Timestamp in UTC of last update
Catalog Asynchronous Workflow: Step 1 of 3
  1. Create a request for the latest catalog of the specified account using the appropriate endpoint.
  2. This action generates a catalogId that represents the account’s catalog.
  3. Catalog requests are cached for 1 hour, meaning repeated requests within this timeframe will return the same catalogId and output.
 

​
Create a Catalog Request for Brand account

This endpoint creates a request for the latest available catalog for a specific account
Best Practice Tip!To speed up catalog downloads, you can narrow down the results by using the brandIdFilter body parameter. This allows you to filter the catalog by specific brands, helping to return results faster.
Sample Request 
curl -L -X POST 'https://api.criteo.com/{version}/retail-media/accounts/4/catalogs' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <MY_ACCESS_TOKEN>' \
--data-raw '{
  "data": {
    "type": "RetailMediaCatalogStatus",
    "attributes": {
      "format": "json-newline",
      "brandIdFilter": [
        "40115",
        "9092"
      ]
    }
  }
}'
Sample Response 
{
    "data": {
        "type": "RetailMediaCatalogStatus",
        "id": "1122850670915847014",
        "attributes": {
            "status": "pending",
            "currency": null,
            "rowCount": null,
            "fileSizeBytes": null,
            "md5Checksum": null,
            "createdAt": "2024-04-06T05:11:41.351+00:00",
            "message": null
        }
    }
}
Catalog Asynchronous Workflow: Step 2 of 3After generating a catalogId, use it to poll the catalog status endpoint to check the progress. Continue polling until the catalog is successfully created and ready for download.
 

​
Create a Catalog Request for Seller account

This endpoint creates catalog for a particular Seller account: Sample Request 
curl --location 'https://api.criteo.com/{version}/retail-media/accounts/345656205021392896/catalogs/sellers' \
--header 'Content-Type: application/json' \
--header 'Accept: text/plain' \
--header 'Authorization: Bearer <TOKEN>' \
--data '{
  "data": {
    "type": "RetailMediaCatalogStatus",
    "attributes": {
      "sellers": [
        {
          "retailerId": "123",
          "sellerId": "60axxxxxxxxxxxxxxxx"
        }
      ]
    }
  }
}'
Sample Response 
{
    "data": {
        "type": "RetailMediaCatalogStatus",
        "id": "1122850670915847014",
        "attributes": {
            "status": "success",
            "currency": "USD",
            "rowCount": 369318,
            "fileSizeBytes": 216634050,
            "md5Checksum": "713f2d3c0ed718125a1acdef05224df5",
            "createdAt": "2025-01-17T22:45:11.44+00:00",
            "message": null
        }
    }
}

​
Get Status of a Specific Catalog

This endpoint retrieves the status of a specific catalog. Status can be pending, success, failure, or expired Sample Request 
curl -X GET "https://api.criteo.com/{version}/retail-media/catalogs/1122850670915847014/status" \
    -H "Authorization: Bearer <MY_ACCESS_TOKEN>"
Sample Response 
{
    "data": {
        "type": "RetailMediaCatalogStatus",
        "id": "1122850670915847014",
        "attributes": {
            "status": "success",
            "currency": "USD",
            "rowCount": 1001,
            "fileSizeBytes": 353293,
            "md5Checksum": "2c15b77740028435ca476823df7fb4f8",
            "createdAt": "2020-04-06T05:11:41.351+00:00",
            "message": null
        }
    }
}
Catalog Asynchronous Workflow: Step 3 of 3Once the catalog is successfully created, use the catalog output endpoint to download the collection of catalog products. Note that catalog outputs are typically available for 72 hours before they expire, so be sure to download them within this time frame.
 

​
Download Output of a Specific Catalog

This endpoint returns the products in a specific catalog as a newline-delimited JSON byte stream Sample Request 
curl -X GET "https://api.criteo.com/{version}/retail-media/catalogs/1122850670915847014/output" \
    -H "Authorization: Bearer <MY_ACCESS_TOKEN>"
Sample Response - Brand Catalog 
{ \
    "id": "sku1", \
    "name": "Product One", \
    "category": "category1", \
    "brandId": "7672171780147256541", \
    "brandName": "Brand 123", \
    "retailerId": "3239117063738827231", \
    "retailerName": "Retailer 123", \
    "price": 1.00, \
    "isInStock": true, \
    "minBid": 0.30, \
    "gtin": "abc123", \
    "mpn": "789xyz", \
    "imageUrl": "/image1.jpg", \
    "updatedAt": "2020-04-06T02:23:07Z" \
}
 
// ... newline-delimited, no comma
 
{ \
    "id": "product-1001", \
    "name": "Product One Thousand and One", \
    "category": "category2", \
    "brandId": "7672171780147256541", \
    "brandName": "Brand 123", \
    "retailerId": "18159942378514859684", \
    "retailerName": "Retailer 789", \
    "price": 5.00, \
    "isInStock": false, \
    "minBid": 0.45, \
    "gtin": "none", \
    "mpn": "none", \
    "imageUrl": "/image1001.jpg", \
    "updatedAt": "2020-04-06T01:07:23Z" \
}
Sample Response - Seller Catalog 
{ \
    "id": "86833674", \
    "name": "Flat Front Short 46 x 10.5\" - Black", \
    "category": "clothing, shoes & accessories|men’s clothing|bottoms|shorts", \
    "categoryId": "3051218", \
    "brandId": "40095", \
    "brandName": "Test Brand", \
    "retailerId": "131", \
    "retailerName": "Retailer Name", \
    "price": 39.99, \
    "isInStock": true, \
    "minBid": 0.4000, \
    "gtin": "1234567890", \
    "mpn": null, \
    "imageUrl": "https://example.com/is/image/a610-881aa9a71c93", \
    "updatedAt": "2024-07-25T19:52:30Z", \
    "sellerId": "60axxxxxxxxxxxxxxxx", \
    "sellerName": "Test Seller" \
}
 
// ... newline-delimited, no comma
 
{ \
    "id": "86833235", \
    "name": "Pleated Front Short 52 x 10.5\" - String", \
    "category": "clothing, shoes & accessories|men’s clothing|bottoms|shorts", \
    "categoryId": "3051218", \
    "brandId": "40095", \
    "brandName": "Test Brand", \
    "retailerId": "131", \
    "retailerName": "Retailer Name", \
    "price": 39.99, \
    "isInStock": true, \
    "minBid": 0.4000, \
    "gtin": "1234567890", \
    "mpn": null, \
    "imageUrl": "https://example.com/is/image/a610-881aa9a71c93", \
    "updatedAt": "2024-07-25T19:52:30Z", \
    "sellerId": "60axxxxxxxxxxxxxxxx", \
    "sellerName": "Test Seller" \
}

​
Responses

ResponseDescription
🟢200Success
🔴400The indicated catalog is not available for retrieval, wait for a success status
🔴403API user does not have the authorization to make requests to the account ID. For an authorization request, follow theauthorization requeststeps