Discard
GuidesAPI ReferenceChangelogDiscussions
GuidesAPI ReferenceChangelogDiscussionsLog In

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}/catalogs Create a Catalog Request
  • GET /catalogs/{catalogId}/status Get Status of a Specific Catalog
  • GET /catalogs/{catalogId}/output Download Output of a Specific Catalog

Catalog Body Parameters

Attribute

Description

Values

Required

format string

Format of the catalog data returned

json-newline

Optional

brandIDFilter string

Brand(s) ids used to filter down catalog results based on specified brands

int64

Optional

Catalog Response Attributes

Attribute

Description

Values

id string

Retailer product ID, established by the retailer

500 char limit

name string

Retailer product name

1000 char limit

category string

Retailer product category

1000 char limit

brandId string

Brand ID of the product

int64

brandName string

Brand name of the product; names are standardized across retailers

120 char limit

retailerId string

Retailer ID carrying the product

int64

retailerName string

Retailer name carrying the product

100 char limit

price number

Retailer product price in USD

isInStock boolean

Whether or not the product is in stock

true, false

minBid number

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

greater than 0

gtin string

Global Trade Item Number (GTIN), if available; also known as European Article Number (EAN) or Universal Product Code (UPC)

mpn string

Manufacturer Part Number (MPN), if available

imageUrl string

Retailer URL for the product image

updatedAt timestamp

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 catalogId representing 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 catalogId to 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" \
}

Did this page help you?