Page Intelligence

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
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.
placementIds	array<string>	No	A filter on the list of placements that are returned in the ad response. If items are in the list

`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<OptimizeOrganicSku>	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.
regionIds	array<string>	No	Store IDs selected by the user when browsing the retailer site.

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, indicateds that the SKU was displayed on the current page of results.
score		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",
  "customerId": "567242992384",
  "regionIds": [
    "us-east"
  ],
  "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
      }
    ]
  }
}

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	Yes	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.

`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	Yes	Name of the product.
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	StructuredBeacon	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.

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

Include the relevant page context and organicSkus in pageAdContext for page intelligence 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
Request succeeded and returned one or more placements, each with a ranked products list.
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.
Authentication failed or token is missing or invalid.	Check API credentials and authorization header.
Internal error while processing the request.

Start here

Feed & Product Data

Requesting Ads

AD Rendering

AD Tracking

Commerce Video

QA checklists

OneTag JavaScript

Google Ad Manager (GAM)

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

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