Insights - Digital Shelf Intelligence

Overview

The Digital Shelf Intelligence API gives brands and advertisers programmatic access to weekly aggregated performance data for products sold through supported retailers. It enables automated retrieval of:

Sales performance data — units sold, sales, and listing prices at brand or SKU level
Visibility and ranking data — PDP views and category-level sales rank
Competitive benchmark indices — relative performance vs. category benchmarks for consideration and sales conversion

The API is designed for users who need to pull shelf intelligence data at scale — integrating it into internal reporting pipelines, BI tools, or automated alerting workflows — without relying on manual dashboard exports. All data is aligned to the retailer’s local time zone and reported in weekly intervals (Monday–Sunday). The report supports two aggregation levels:

Brand-level — metrics grouped across all SKUs belonging to a brand (portfolio tracking, brand vs. category benchmarking, retailer comparisons)
SKU-level — metrics reported per individual product (performance diagnostics, assortment optimization, PDP traffic and conversion analysis)

You can find the Digital Shelf Intelligence endpoints in the API Reference under Insights.

Endpoints

Verb	Endpoint	Description
`POST`	`/experimental/retail-media/insights/digital-shelf-intelligence`	Submit a Digital Shelf Intelligence report request
`GET`	`/experimental/retail-media/insights/{reportId}/status`	Poll the status of a submitted report
`GET`	`/experimental/retail-media/insights/{reportId}/output`	Retrieve the output of a completed report

Dimensions

Dimensions describe how report data is grouped. The dimension set is fixed by aggregationLevel — clients do not provide a custom dimensions list.

Time dimensions

Dimension	Description
`startDate`	Start of the reporting week (always a Monday)
`endDate`	End of the reporting week (always a Sunday, inclusive)

Retailer dimensions

Dimension	Description
`retailerId`	Unique identifier for the retailer
`retailerName`	Display name of the retailer

Product & taxonomy dimensions

Dimension	Availability	Description
`category`	Brand & SKU	Product category
`brandId`	Brand only	Unique identifier for the brand
`brandName`	Brand only	Brand name
`skuId`	SKU only	Retailer-specific SKU identifier
`skuName`	SKU only	Retailer-specific product name

Metrics

Metrics represent performance, sales, and visibility indicators. Availability varies by aggregation level.

Commercial performance

Metric	Availability	Description
`totalSalesOnline`	Brand & SKU	Total online sales, in the account’s local currency
`totalSoldUnitsOnline`	Brand & SKU	Total number of units sold online
`listingPrice`	SKU only	Product listing price from the retailer catalog

Visibility & ranking

Metric	Availability	Description
`totalPdpPageViews`	Brand & SKU	Total product detail page (PDP) views
`pdpViewRank`	Brand & SKU	Rank of products by PDP views within the category
`salesRank`	Brand & SKU	Rank of products by total sales within the category

Performance indices

Metric	Availability	Description
`considerationIndex`	Brand & SKU	Relative PDP views per SKU vs. category benchmark. Values >1 indicate above benchmark.
`salesIndex`	Brand & SKU	Relative sales per PDP view vs. category benchmark. Values >1 indicate above benchmark.

Endpoint: Submit report request

Submit a Digital Shelf Intelligence report job. The API is asynchronous — this call returns a reportId to poll for results.

Request attributes

Attribute	Type	Required	Description
`accountId`	`string`	Yes	External Retail Media account ID. Must be numeric.
`startDate`	`string` (date)	Yes	Inclusive start date. If not a Monday, the report is accepted and shifted back to the Monday of that week, with a warning.
`endDate`	`string` (date)	Yes	Inclusive end date. If not a Sunday, the report is accepted and shifted forward to the Sunday of that week, with a warning.
`aggregationLevel`	`string`	Yes	One of `brand` or `sku`.
`metrics`	`string[]`	Yes	At least one metric. Allowed values: `considerationIndex`, `listingPrice`, `pdpViewRank`, `salesIndex`, `salesRank`, `totalPdpPageViews`, `totalSalesOnline`, `totalSoldUnitsOnline`.
`retailerIds`	`string[]`	No	Retailer IDs to filter on. Must be numeric internal IDs.
`brandIds`	`string[]`	No	Brand IDs to filter on. Must be numeric external IDs.
`skuIds`	`object[]`	No	SKU filters grouped by retailer. Ignored with a warning when `aggregationLevel` is `brand`. Each entry requires `retailerId` (string) and `retailerSkuIds` (string[]).
`categories`	`string[]`	No	Category names to filter on.
`format`	`string`	No	Output format. One of `json`, `json-compact`, `json-newline`, `csv`. Default: `json-compact`.

startDate must not be after endDate, and the requested interval must be 100 days or less.

Sample request

curl --request POST \
  --url 'https://api.criteo.com/experimental/retail-media/insights/digital-shelf-intelligence' \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
    "data": {
      "attributes": {
        "accountId": "123",
        "startDate": "2025-08-11",
        "endDate": "2025-08-17",
        "aggregationLevel": "sku",
        "metrics": ["totalSalesOnline", "totalSoldUnitsOnline", "listingPrice"],
        "retailerIds": ["101", "102"],
        "brandIds": ["2001", "2002"],
        "skuIds": [
          {
            "retailerId": "101",
            "retailerSkuIds": ["sku-001", "sku-002"]
          }
        ],
        "categories": ["Beverages", "Snacks"],
        "format": "json-compact"
      }
    }
  }'

import requests

url = "https://api.criteo.com/experimental/retail-media/insights/digital-shelf-intelligence"
headers = {
    "Authorization": "Bearer <ACCESS_TOKEN>",
    "Content-Type": "application/json",
}
payload = {
    "data": {
        "attributes": {
            "accountId": "123",
            "startDate": "2025-08-11",
            "endDate": "2025-08-17",
            "aggregationLevel": "sku",
            "metrics": ["totalSalesOnline", "totalSoldUnitsOnline", "listingPrice"],
            "retailerIds": ["101", "102"],
            "brandIds": ["2001", "2002"],
            "skuIds": [{"retailerId": "101", "retailerSkuIds": ["sku-001", "sku-002"]}],
            "categories": ["Beverages", "Snacks"],
            "format": "json-compact",
        }
    }
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())

OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, """
{
  "data": {
    "attributes": {
      "accountId": "123",
      "startDate": "2025-08-11",
      "endDate": "2025-08-17",
      "aggregationLevel": "sku",
      "metrics": ["totalSalesOnline", "totalSoldUnitsOnline", "listingPrice"],
      "retailerIds": ["101", "102"],
      "brandIds": ["2001", "2002"],
      "skuIds": [{"retailerId": "101", "retailerSkuIds": ["sku-001", "sku-002"]}],
      "categories": ["Beverages", "Snacks"],
      "format": "json-compact"
    }
  }
}
""");

Request request = new Request.Builder()
  .url("https://api.criteo.com/experimental/retail-media/insights/digital-shelf-intelligence")
  .post(body)
  .addHeader("Authorization", "Bearer <ACCESS_TOKEN>")
  .addHeader("Content-Type", "application/json")
  .build();

Response response = client.newCall(request).execute();

$request = new HTTP_Request2();
$request->setUrl('https://api.criteo.com/experimental/retail-media/insights/digital-shelf-intelligence');
$request->setMethod(HTTP_Request2::METHOD_POST);
$request->setHeader(['Authorization' => 'Bearer <ACCESS_TOKEN>', 'Content-Type' => 'application/json']);
$request->setBody(json_encode([
    'data' => [
        'attributes' => [
            'accountId' => '123',
            'startDate' => '2025-08-11',
            'endDate' => '2025-08-17',
            'aggregationLevel' => 'sku',
            'metrics' => ['totalSalesOnline', 'totalSoldUnitsOnline', 'listingPrice'],
            'retailerIds' => ['101', '102'],
            'brandIds' => ['2001', '2002'],
            'skuIds' => [['retailerId' => '101', 'retailerSkuIds' => ['sku-001', 'sku-002']]],
            'categories' => ['Beverages', 'Snacks'],
            'format' => 'json-compact',
        ],
    ],
]));

echo $request->send()->getBody();

Sample response

{
  "data": {
    "id": "87a8e280-9cc9-47f3-9bf9-b68e947cade5",
    "type": "InsightStatusResponse",
    "attributes": {
      "status": "Pending",
      "message": null,
      "createdAt": "2026-06-12T14:57:07.336Z",
      "expiresAt": null,
      "rowCount": null,
      "md5CheckSum": null,
      "fileSizeBytes": null
    }
  },
  "warnings": [],
  "errors": []
}

Endpoint: Poll report status

Check whether a submitted report job has completed. Returns status: "Pending" while processing, or HTTP 410 if the report failed, expired, or was invalidated.

Sample request

curl --request GET \
  --url 'https://api.criteo.com/experimental/retail-media/insights/<REPORT_ID>/status' \
  --header 'Authorization: Bearer <ACCESS_TOKEN>'

import requests

response = requests.get(
    "https://api.criteo.com/experimental/retail-media/insights/<REPORT_ID>/status",
    headers={"Authorization": "Bearer <ACCESS_TOKEN>"},
)
print(response.json())

Request request = new Request.Builder()
  .url("https://api.criteo.com/experimental/retail-media/insights/<REPORT_ID>/status")
  .get()
  .addHeader("Authorization", "Bearer <ACCESS_TOKEN>")
  .build();

Response response = client.newCall(request).execute();

$request = new HTTP_Request2();
$request->setUrl('https://api.criteo.com/experimental/retail-media/insights/<REPORT_ID>/status');
$request->setMethod(HTTP_Request2::METHOD_GET);
$request->setHeader(['Authorization' => 'Bearer <ACCESS_TOKEN>']);
echo $request->send()->getBody();

Sample response

{
  "data": {
    "id": "87a8e280-9cc9-47f3-9bf9-b68e947cade5",
    "type": "InsightStatusResponse",
    "attributes": {
      "status": "Success",
      "message": null,
      "createdAt": "2026-06-12T15:00:43.000Z",
      "expiresAt": "2026-06-19T15:00:43.000Z",
      "rowCount": 0,
      "md5CheckSum": "d41d8cd98f00b204e9800998ecf8427e",
      "fileSizeBytes": 0
    }
  },
  "warnings": [],
  "errors": []
}

Endpoint: Retrieve report output

Download the results of a completed report. Only succeeds when report status is Success. Returns HTTP 400 with code insight-not-ready if the report is still Pending.

Sample request

curl --request GET \
  --url 'https://api.criteo.com/experimental/retail-media/insights/<REPORT_ID>/output' \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'Accept: text/plain'

import requests

response = requests.get(
    "https://api.criteo.com/experimental/retail-media/insights/<REPORT_ID>/output",
    headers={"Authorization": "Bearer <ACCESS_TOKEN>", "Accept": "text/plain"},
)
print(response.text)

Request request = new Request.Builder()
  .url("https://api.criteo.com/experimental/retail-media/insights/<REPORT_ID>/output")
  .get()
  .addHeader("Authorization", "Bearer <ACCESS_TOKEN>")
  .addHeader("Accept", "text/plain")
  .build();

Response response = client.newCall(request).execute();

$request = new HTTP_Request2();
$request->setUrl('https://api.criteo.com/experimental/retail-media/insights/<REPORT_ID>/output');
$request->setMethod(HTTP_Request2::METHOD_GET);
$request->setHeader(['Authorization' => 'Bearer <ACCESS_TOKEN>', 'Accept' => 'text/plain']);
echo $request->send()->getBody();

Sample response

{"columns":["startDate","endDate","retailerId","retailerName","category","skuId","skuName","considerationIndex"],
"data":[],
"rows":0}

Responses

HTTP status	Code	Description	Troubleshooting
`200 OK`	—	Report accepted. Response contains `reportId` in `data.id`.	Poll `/insights/{reportId}/status` until status is `Success`.
`200 OK`	—	`status: "Pending"` — report is still processing.	Retry the status call later.
`200 OK`	—	`status: "Success"` — output is ready.	Call `/insights/{reportId}/output` to download.
`200 OK` + warning	`invalid-date`	`startDate` not a Monday or `endDate` not a Sunday. Request accepted and shifted to week boundaries.	Send Monday–Sunday dates to avoid auto-adjustment warnings.
`200 OK` + warning	`incompatible-filter`	`skuIds` sent with `aggregationLevel: brand` — filter ignored.	Use `aggregationLevel: sku` when filtering by SKU.
`200 OK` + warning	`invalid-metric`	`listingPrice` requested with `aggregationLevel: brand` — metric omitted.	Use `aggregationLevel: sku` when requesting `listingPrice`.
`400 Bad Request`	`attribute-required`	Missing required attribute, invalid ID format, `startDate > endDate`, or interval > 100 days.	Validate the request body before submitting.
`400 Bad Request`	`insight-not-ready`	Output endpoint called before report reached `Success`.	Poll the status endpoint first.
`403 Forbidden`	`forbidden`	Caller not allowed to access the requested account or endpoint.	Confirm account permissions and feature enablement.
`404 Not Found`	`insight-not-found`	Report ID does not exist.	Verify the `reportId` and try again.
`410 Gone`	`insight-failed`	Report execution failed.	Submit a new report request.
`410 Gone`	`insight-invalidated`	Report invalidated and no longer available.	Submit a new report request.
`410 Gone`	`insight-expired`	Report expired and no longer available.	Submit a new report request.

Introduction

Concepts

RESOURCES

Guides for Retail Media API

Insights - Digital Shelf Intelligence

Overview

Endpoints

Dimensions

Time dimensions

Retailer dimensions

Product & taxonomy dimensions

Metrics

Commercial performance

Visibility & ranking

Performance indices

Endpoint: Submit report request

Request attributes

Sample request

Sample response

Endpoint: Poll report status

Sample request

Sample response

Endpoint: Retrieve report output

Sample request

Sample response

Responses

​Overview

​Endpoints

​Dimensions

​Time dimensions

​Retailer dimensions

​Product & taxonomy dimensions

​Metrics

​Commercial performance

​Visibility & ranking

​Performance indices

​Endpoint: Submit report request

​Request attributes

​Sample request

​Sample response

​Endpoint: Poll report status

​Sample request

​Sample response

​Endpoint: Retrieve report output

​Sample request

​Sample response

​Responses

Overview

Endpoints

Dimensions

Time dimensions

Retailer dimensions

Product & taxonomy dimensions

Metrics

Commercial performance

Visibility & ranking

Performance indices

Endpoint: Submit report request

Request attributes

Sample request

Sample response

Endpoint: Poll report status

Sample request

Sample response

Endpoint: Retrieve report output

Sample request

Sample response

Responses