Catalog endpoints
- A catalog is a snapshot of all catalog products from brands & retailers associated with the account, typically updated once a day
- Each account has one catalog specifying all the products the account is eligible to promote
- Catalogs are requested & retrieved through asynchronous endpoints
- Product attributes are scoped to the retailer except for universal IDs such as GTIN, if available
- Brand attributes are standardized across retailers
- Catalogs are in the currency of the retailer
- Catalog outputs are UTF-8 encoded
Endpoints
POST /accounts/{accountId}/catalogsCreate a Catalog RequestGET /catalogs/{catalogId}/statusGet Status of a Specific CatalogGET /catalogs/{catalogId}/outputDownload Output of a Specific Catalog
Catalog Body Parameters
Attribute | Description | Values | Required |
|---|---|---|---|
| Format of the catalog data returned |
| Optional |
| Brand(s) ids used to filter down catalog results based on specified brands | int64 | Optional |
Catalog Response Attributes
Attribute | Description | Values |
|---|---|---|
| Retailer product ID, established by the retailer | 500 char limit |
| Retailer product name | 1000 char limit |
| Retailer product category | 1000 char limit |
| Brand ID of the product | int64 |
| Brand name of the product; names are standardized across retailers | 120 char limit |
| Retailer ID carrying the product | int64 |
| Retailer name carrying the product | 100 char limit |
| Retailer product price in USD | |
| Whether or not the product is in stock |
|
| Minimum Cost-Per-Click (CPC) an advertiser must bid for the product, established by the retailer; any line item with this product must have | greater than 0 |
| Global Trade Item Number (GTIN), if available; also known as European Article Number (EAN) or Universal Product Code (UPC) | |
| Manufacturer Part Number (MPN), if available | |
| Retailer URL for the product image | |
| Timestamp in UTC of last update | ISO-8601 |
Catalog Asynchronous Workflow: Step 1 of 3
- First, create a request for the latest catalog of the specified account
- This generates a
catalogIdrepresenting the account catalog- Catalog requests are cached for 1 hour
Create a Catalog Request
- This endpoint creates a request for the latest available catalog for a specific account
https://api.criteo.com/2021-10/retail-media/accounts/{accountId}/catalogs
Sample Request
curl -L -X POST 'https://api.criteo.com/2022-04/retail-media/accounts/4/catalogs' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer myaccesstoken' \
--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": "2020-04-06T05:11:41.351+00:00",
"message": null
}
}
}
Catalog Asynchronous Workflow: Step 2 of 3
- Next, use the
catalogIdto poll the catalog status endpoint until one is successfully created
Get Status of a Specific Catalog
This endpoint retrieves the status of a specific catalog. Status can be pending, success, failure, or expired
https://api.criteo.com/2021-10/retail-media/catalogs/{catalogId}/status
Sample Request
curl -X GET "https://api.criteo.com/2022-04/retail-media/catalogs/1122850670915847014/status" \
-H "Authorization: Bearer myaccesstoken"
Sample Response
{
"data": {
"type": "RetailMediaCatalogStatus",
"id": "1122850670915847014"
"attributes": {
"status": "pending",
"currency": null,
"rowCount": null,
"fileSizeBytes": null,
"md5Checksum": null,
"createdAt": "2020-04-06T05:11:41.351+00:00",
"message": null
}
}
}
Sample Request
curl -X GET "https://api.criteo.com/2022-04/retail-media/catalogs/1122850670915847014/status" \
-H "Authorization: Bearer myaccesstoken"
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 3
- Finally, download the collection of catalog products using the catalog output endpoint
- Catalog outputs typically have an expiration of 72 hours
Download Output of a Specific Catalog
- This endpoint returns the products in a specific catalog as a newline-delimited JSON byte stream
https://api.criteo.com/2021-10/retail-media/catalogs/{catalogId}/output
Sample Request
curl -X GET "https://api.criteo.com/2022-04/retail-media/catalogs/1122850670915847014/output" \
-H "Authorization: Bearer myaccesstoken"
Sample Response
{ \
"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" \
}
Updated 13 days ago