> ## Documentation Index > Fetch the complete documentation index at: https://developers.criteo.com/llms.txt > Use this file to discover all available pages before exploring further. # 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

POST

[https://api.criteo.com/v1/partners/\{partnerId\}/optimize](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\

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\

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\

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 ```json theme={null} { "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\

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\

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 ```json expandable theme={null} { "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](/retailer-integration/docs/beacon-sdk), 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.