Page Intelligence - Criteo Docs

This guide introduces the Page Intelligence endpoint, its request and response objects, and the expected integration behavior for retailers using holistic optimization across organic and sponsored products.

Business Context

Page Intelligence helps retailers optimize search and category pages holistically by evaluating organic and sponsored products together instead of managing them through separate decisioning flows. It uses the same Sponsored Products campaigns and reporting, while adding a unified scoring and policy layer so retailers can control how sponsored SKUs appear across placements without compromising relevance or shopper experience.

Page Intelligence does not replace Sponsored Products.It uses the same Sponsored Products campaigns and reporting, but offers an additional way to orchestrate where and how sponsored SKUs appear across placements on your page.You can enable it on selected search and category pages while keeping your existing Sponsored Products integration elsewhere.

Endpoint Behavior

Page Intelligence helps retailers maximize page-level value by balancing organic and sponsored products across placements using a unified scoring and policy layer. The endpoint lets you:

Send page context and organic candidates for placements that require holistic optimization.
Receive multiple optimized placements, each with its own ranked list of products.
Implement both product-level and placement-level beacons for measurement and model training.

The updated contract is designed to support multiple placements and align more closely with existing delivery behavior across placement types.

Prerequisites

The retailer is already integrated with Criteo Retail Media Delivery.
Page Intelligence configuration and policy settings are set up with your Criteo team.
You can send a stable retailerVisitorId and relevant page context.

Recommendations

Do not re-rank the products returned in each placement.
Implement both product-level and placement-level beacons from the response.
Include organicSkus for requests that use holistic optimization.

Endpoint Overview

Method	Endpoint	Description
`POST`	`https://api.criteo.com/v1/partners/{partnerId}/optimize`	Optimize one or more placements across organic and sponsored products using a unified scoring and policy layer.

Request Body

Top-level request object

Attribute	Data type	Required	Description
`pageId`	`string`	Yes	ID of the page that this ad call is for.
`pageAdContext`	`OptimizeAdContext`	No	Page context for the ad request. Contains composable properties that inform ad selection algorithms based on page content and context.
`retailerVisitorId`	`string`	No	Unique, unauthenticated user ID persisted across sessions on the same device. Can be a string ID or SHA256-hashed email.
`customerId`	`string`	No	Unique ID of the authenticated user for the current session.
`regionId`	`string`	No	Store ID selected by the user when browsing the retailer site.

`OptimizeAdContext`

The pageAdContext object uses a flat, composable structure. Each property can be included or omitted depending on the content and context needed for each ad request.

Attribute	Data type	Required	Description
`keywords`	`string`	No	Keyword search string entered by the user.
`category`	`string`	No	Category or taxonomy text of the page the user is browsing.
`organicSkus`	`array<OrganicSku>`	No*	Organic SKUs returned by a search query or category in rank order. Up to 1000 values. Required for ad calls that utilize HPO.
`filters`	`array<RequestFilter>`	No	Filters applied by the shopper on the result set. Up to 10 filters.
`pageNumber`	`integer`	No	Page number for paginated results or dynamically loaded result folds.
`productId`	`string`	No	SKU ID corresponding to the product on a product detail page.
`price`	`float`	No	Current price of the product added to the basket, including discount if any.
`availability`	`boolean`	No	Whether the product is in stock.

Required for requests that use holistic optimization.

`OrganicSku`

Attribute	Data type	Required	Description
`skuId`	`string`	Yes	ID of the organic SKU.
`isDisplayedOnCurrentPage`	`boolean`	Yes	If`true`, indicates that the SKU was displayed on the current page of results.
`score`	`float`	No	Quality or relevancy score assigned by the retailer to this SKU.

`RequestFilter`

Attribute	Data type	Required	Description
`name`	`string`	Yes	Name of the filter.
`operator`	`OperatorEnum`	Yes	Filter operator.
`value`	`array<string>`	Yes	Values the operator applies to. Up to 10 values.

In and NotIn support multiple values. The other operators support a single value.

`OperatorEnum`

Value	Description
`Equal`	Equal to.
`GreaterThan`	Greater than.
`LessThan`	Less than.
`GreaterThanOrEqual`	Greater than or equal to.
`LessThanOrEqual`	Less than or equal to.
`In`	Membership in a list.
`NotEqual`	Not equal to.
`NotIn`	Not in the membership list.

Sample Request

{
  "pageId": "hpo_searchPage_desktop",
  "pageAdContext": {
    "keywords": "windows",
    "filters": [
      {
        "name": "color",
        "operator": "Equal",
        "value": ["blue"]
      }
    ],
    "pageNumber": 1,
    "organicSkus": [
      {
        "skuId": "5454644",
        "isDisplayedOnCurrentPage": true,
        "score": 0.98
      },
      {
        "skuId": "1005000",
        "isDisplayedOnCurrentPage": true,
        "score": 0.97
      }
    ]
  },
  "customerId": "567242992384",
  "regionId": "us-east"
}

Response Body

The response supports multiple placements in a single response. Each placement has its own format, products, and placement-level beacons. The response uses a resource-style envelope with data.type and data.attributes.

Response overview

Attribute	Data type	Required	Description
`data`	`OptimizeData`	Yes	Response data payload.
`warnings`	`array`	No	Warnings about this specific request.
`errors`	`array`	No	Errors that happened while handling this request.

The data object includes a type field set to "OptimizeData" and an attributes object containing the actual response payload.

`OptimizeData`

Attribute	Data type	Required	Description
`pageUid`	`string`	Yes	Unique ID of this optimize response, used for debugging purposes.
`placements`	`dictionary<string, OptimizePlacement>`	Yes	List of placements returned in the response. The key is the placement name.

`OptimizePlacement`

Attribute	Data type	Required	Description
`placementId`	`string`	Example response	Placement identifier shown in the current contract example response.
`format`	`string`	Yes	Ad format of the placement.
`products`	`array<OptimizeProduct>`	Yes	List of products to include in the placement. Can include both ads and organic product results.
`beacons`	`OptimizePlacementBeacons`	Yes	Placement-level tracking beacons.
`vastTagUrl`	`string`	No	VAST tag URL for video ad formats.
`vastTagXml`	`string`	No	VAST tag XML for video ad formats.

`OptimizeProduct`

Attribute	Data type	Required	Description
`listingType`	`ListingType`	Yes	Type of product, such as organic or sponsored.
`skuId`	`string`	Yes	SKU ID of the product.
`parentSkuId`	`string`	Yes	Parent SKU ID. If the product does not have a parent, its own ID is used.
`productName`	`string`	Example response	Product name shown in the current contract example response.
`productPageUrl`	`string`	No	URL for the product detail page.
`productImageUrl`	`string`	No	URL for the product image.
`rating`	`string`	No	Product rating.
`price`	`string`	Yes	Current price in the retailer’s currency.
`comparePrice`	`string`	No	Original price before discount, if any.
`renderingAttributes`	`string`	No	Retailer-provided JSON-serialized dictionary of additional rendering properties.
`beacons`	`OptimizeProductBeacons`	Yes	Product-level tracking beacons for this product.

Placement-level beacons

Attribute	Data type	Required	Description
`onLoadBeacon`	`object`	Yes	Structured beacon to fire when the placement is loaded. See StructuredBeacon below.
`onViewBeacon`	`string`	Yes	URL to call when the placement is viewed according to IAB guidelines.
`onClickBeacon`	`string`	No	URL to call when the placement is clicked.

StructuredBeacon

The placement onLoadBeacon returned from the /optimize endpoint is always a StructuredBeacon object — not a plain URL string. This format supports large payloads (up to 100 organic SKUs) by splitting the beacon into a base URL and a set of key-value parameters sent as the POST body.

Field	Type	Description
`url`	`string`	Base beacon URL.
`payload`	`object`	Key-value pairs to send as the `application/x-www-form-urlencoded` POST body via `navigator.sendBeacon(url, data)`. Criteo returns `rm_e` (encrypted beacon string). The following keys are not returned by the API and must be populated by the retailer before firing the beacon: `sku` (rendered SKU IDs for painted slots), `slot` (slot indices), `ex` (unrendered/suppressed SKU IDs), and `st` (exclusion reasons).

Product-level beacons

Attribute	Data type	Required	Description
`onViewBeacon`	`string`	Yes	URL to call when the product is viewed according to IAB guidelines.
`onClickBeacon`	`string`	Yes	URL to call when the product is clicked.
`onBasketChangeBeacon`	`string`	Yes	URL to call when the product is added to the basket.
`onWishlistBeacon`	`string`	Yes	URL to call when the product is added to a wishlist.

Sample Response

{
  "data": {
    "type": "OptimizeData",
    "attributes": {
      "pageUid": "ef47a7cc-a703-4775-8032-24145a6a0c0a",
      "placements": {
        "viewSearchResult_API_desktop-Carousel": {
          "placementId": "viewSearchResult_API_desktop-Carousel",
          "format": "sponsored_products",
          "products": [
            {
              "listingType": "Sponsored",
              "skuId": "6887924",
              "parentSkuId": "6887924",
              "productName": "Example product",
              "productPageUrl": "https://www.example.com/product/6887924",
              "productImageUrl": "https://www.example.com/images/6887924.jpg",
              "rating": "4.0000",
              "price": "10.00",
              "comparePrice": "44.49",
              "renderingAttributes": "{\"brand\":\"example\"}",
              "beacons": {
                "onViewBeacon": "//b.example/rm?...",
                "onClickBeacon": "//b.example/rm?...",
                "onBasketChangeBeacon": "//b.example/rm?...",
                "onWishlistBeacon": "//b.example/rm?..."
              }
            }
          ],
          "beacons": {
            "onLoadBeacon": {
              "url": "//b.example/rm?u=1&ev=4",
              "payload": {
                "rm_e": "4cp0JZowKy..."
              }
            },
            "onViewBeacon": "//b.example/rm?...",
            "onClickBeacon": "//b.example/rm?..."
          }
        },
        "viewSearchResult_API_desktop-InGrid": {
          "placementId": "viewSearchResult_API_desktop-InGrid",
          "format": "page_intelligence",
          "products": [
            {
              "listingType": "Sponsored",
              "skuId": "6887100",
              "parentSkuId": "6887100",
              "productName": "Example sponsored product",
              "productPageUrl": "https://www.example.com/product/6887100",
              "productImageUrl": "https://www.example.com/images/6887100.jpg",
              "rating": "4.0000",
              "price": "10.00",
              "comparePrice": "44.49",
              "renderingAttributes": "{\"brand\":\"example\"}",
              "beacons": {
                "onViewBeacon": "//b.example/rm?...",
                "onClickBeacon": "//b.example/rm?...",
                "onBasketChangeBeacon": "",
                "onWishlistBeacon": ""
              }
            },
            {
              "listingType": "Organic",
              "skuId": "5454644",
              "parentSkuId": null,
              "productName": null,
              "productPageUrl": "https://www.example.com/product/5454644",
              "productImageUrl": "https://www.example.com/images/5454644.jpg",
              "rating": "2.5000",
              "price": "48.99",
              "comparePrice": "48.99",
              "renderingAttributes": "{\"brand\":\"example\"}",
              "beacons": {
                "onViewBeacon": "",
                "onClickBeacon": "//b.example/rm?...",
                "onBasketChangeBeacon": "//b.example/rm?...",
                "onWishlistBeacon": "//b.example/rm?..."
              }
            }
          ],
          "beacons": {
            "onLoadBeacon": {
              "url": "//b.example/rm?u=1&ev=4",
              "payload": {
                "rm_e": "4cp0JZowKy..."
              }
            },
            "onViewBeacon": null,
            "onClickBeacon": null
          }
        }
      }
    }
  },
  "warnings": [],
  "errors": []
}

Integration Notes

Use this endpoint on pages where you want Criteo to optimize across organic and sponsored products together.
Include the relevant page context and organicSkus in pageAdContext for holistic optimization scenarios.
Render each placement exactly as returned.
Implement all beacons returned in the response. For placement onLoadBeacon, fire the beacon using navigator.sendBeacon(url, data) where url is StructuredBeacon.url and data is the payload serialized as application/x-www-form-urlencoded. If navigator.sendBeacon is not available, use a POST request with the same form-encoded body.
If using BeaconSDK, set data-criteo-placement-onloadbeacon to the url value and add one data-criteo-placement-onloadbeacon-payload-[key] attribute per entry in the payload object on the placement element. BeaconSDK handles the navigator.sendBeacon(url, data) call automatically.

Response Codes

Response code	Title	Detail	Troubleshooting
`200`	`OK`	Request succeeded and returned one or more placements, each with a ranked products list.	Render each placement as-is, use`listingType`for labeling, and implement both product-level and placement-level beacons correctly.
`400`	`Bad Request`	Request body is invalid, for example because required fields are missing or the filter structure is invalid.	Verify that required attributes are present and that the request structure is valid.
`401`	`Unauthorized`	Authentication failed or token is missing or invalid.	Check API credentials and authorization header.
`5xx`	`Server error`	Internal error while processing the request.	Retry with backoff. If the issue persists, contact your Criteo representative with`pageUid`and timeframe.

​Business Context

​Endpoint Behavior

​Prerequisites

​Recommendations

​Endpoint Overview

​Request Body

​Top-level request object

​OptimizeAdContext

​OrganicSku

​RequestFilter

​OperatorEnum

​Sample Request

​Response Body

​Response overview

​OptimizeData

​OptimizePlacement

​OptimizeProduct

​Placement-level beacons

​StructuredBeacon

​Product-level beacons

​Sample Response

​Integration Notes

​Response Codes

Business Context

Endpoint Behavior

Prerequisites

Recommendations

Endpoint Overview

Request Body

Top-level request object

`OptimizeAdContext`

`OrganicSku`

`RequestFilter`

`OperatorEnum`

Sample Request

Response Body

Response overview

`OptimizeData`

`OptimizePlacement`

`OptimizeProduct`

Placement-level beacons

StructuredBeacon

Product-level beacons

Sample Response

Integration Notes

Response Codes