---
title: Integrate a retail media network for sponsored products
slug: q3gb2197
canonical_url: https://docs.coveo.com/en/q3gb2197/
collection: coveo-for-commerce
source_format: adoc
---
# Integrate a retail media network for sponsored products
When using Relevance-Aware Sponsored Products, merchandisers can reserve positions for sponsored products in the [Coveo Merchandising Hub (CMH)](https://docs.coveo.com/en/o5290573/).
Sponsored products can be defined manually by merchandisers in the CMH, or they can be sent by a third-party retail media network at query time.

This article explains how to integrate a retail media network with the Commerce API.
This approach offers several advantages:

* **Relevance guardrail**: Coveo filters out sponsored candidates that aren't relevant to the current query, so only contextually appropriate products fill reserved positions.

* **Centralized control**: Merchandisers manage the number and placement of sponsored positions in the CMH, independent of the ad engine.

* **Single result set**: Your [storefront](https://docs.coveo.com/en/p33g0410/) receives one API response with sponsored products already merged into the organic results, respecting active [facets](https://docs.coveo.com/en/198/), page size, and sorting.

> **Important**
>
> Contact your Coveo representative to enable Relevance-Aware Sponsored Products in your [Coveo organization](https://docs.coveo.com/en/185/).

## How the integration works

The integration follows a sequential flow:

. Your [storefront](https://docs.coveo.com/en/p33g0410/) calls the retail media network (ad engine) to retrieve a sorted list of sponsored product candidates, pre-filtered by the ad engine for a target category or [keyword](https://docs.coveo.com/en/2738/).

. Your [storefront](https://docs.coveo.com/en/p33g0410/) passes the list of product IDs to the Coveo Commerce API in the [Search](https://docs.coveo.com/en/103/api-reference/commerce-api#tag/Search/operation/search) or https://docs.coveo.com/en/103/api-reference/commerce-api#tag/Listings[Listings^] endpoint using the `pinnedProducts` parameter.

. Coveo processes the candidate list against the reserved sponsored positions (as defined in the CMH when setting up Relevance-Aware Sponsored Products for [search](https://docs.coveo.com/en/q2pf0033/) and for [product listing pages](https://docs.coveo.com/en/pakd0058/)).
The list should contain more candidates than there are reserved positions, to provide fallback options if some candidates are filtered out by index ranking or manual facet refinements.

. Coveo returns the response, which includes a `queryPinned` Boolean attribute on each product that was placed into a reserved sponsored position, confirming that the product is the result of the sponsored candidates received.

> **Note**
>
> The calls to the retail media network and to Coveo must be sequential, not parallel, because the retail media network's output is an input to the Coveo request.
> Apply a strict timeout on the call to the retail media network to avoid impacting the overall latency of the search results.

## Prerequisites

* Relevance-Aware Sponsored Products must be enabled on your [Coveo organization](https://docs.coveo.com/en/185/).
Contact your Coveo representative.

* At least one sponsored product pin rule must be configured in the CMH.
See [Relevance-Aware Sponsored Product pin rules for search](https://docs.coveo.com/en/q2pf0033/) or [Relevance-Aware Sponsored Product pin rules for product listing pages](https://docs.coveo.com/en/pakd0058/).

## Pass sponsored product candidates in the request

First, call your retail media network to retrieve sponsored product candidates for the current query or listing context.
The response format varies by provider, but typically includes product IDs and priority information.
The order of the product IDs in the list should reflect their priority for filling the reserved sponsored positions (first ID has highest priority).

Sample retail media network response:

```json
[
  {"productId": "SP00123_00001", "bid": 2.50, "campaignId": "camp_abc"},
  {"productId": "SP00456_00002", "bid": 1.75, "campaignId": "camp_def"},
  {"productId": "SP00789_00003", "bid": 1.20, "campaignId": "camp_abc"}
]
```

> **Note**
>
> Bid values aren't required by Coveo, but the sort order of the list defines the priority used to fill the inventory of reserved positions.

Pass the product IDs in priority order to the `pinnedProducts` parameter when calling the Commerce API [Search](https://docs.coveo.com/en/103/api-reference/commerce-api#tag/Search/operation/search) or https://docs.coveo.com/en/103/api-reference/commerce-api#tag/Listings[Listings^] endpoint.
The `pinnedProducts` parameter accepts an array of product IDs, sorted by priority (first ID has highest priority).

Sample search request with `pinnedProducts`:

```json
{
  "trackingId": "my_tracking_id",
  "language": "en",
  "country": "US",
  "currency": "USD",
  "clientId": "58bb4b98-1daa-4767-8c15-90a0ea67645c",
  "query": "sandals",
  "pinnedProducts": ["SP00123_00001", "SP00456_00002", "SP00789_00003"],
  "context": {
    "view": {
      "url": "https://mystore.example.com/search"
    }
  }
}
```

When processing the candidate list, Coveo applies the following behaviors:

* **Organic retrieval**: Only candidates that appear in the organic retrieval for the current query or listing page are eligible to fill a reserved position.
To enable cross-selling from outside the organic retrieval (for example, for cross-category promotion), contact your Coveo representative to configure this option on the applicable rule.

* **Fallback**: If a candidate isn't eligible, Coveo falls back on the next candidate in the list to try to fill all reserved positions.
If the entire candidate list is exhausted, remaining positions fall back to any products defined manually in the CMH sponsored product pin rule.

## Identify sponsored products in the response

In the Commerce API response, each product object includes a `queryPinned` Boolean attribute.
When `queryPinned` is `true`, the product was pinned into a reserved sponsored position.

Sample product object in the response:

```json
{
  "ec_name": "Limespace Sport Sandals",
  "ec_brand": "Limespace",
  "ec_price": 49.99,
  "permanentid": "SP00123_00001",
  "queryPinned": true,
  "clickUri": "https://mystore.example.com/product/SP00123_00001"
}
```

> **Leading practice**
>
> Use the `queryPinned` attribute to render a visual indicator (such as a "Sponsored" label) on the [storefront](https://docs.coveo.com/en/p33g0410/), so that users can distinguish sponsored products from organic results.

## Limitations

* **Pin rule limits**: Each [Coveo organization](https://docs.coveo.com/en/185/) supports up to 100 pin rules per query.
Fallback candidates count against this limit.
For example, if 5 sponsored positions are configured and 20 product candidates are received, this can create close to 100 potential rules to evaluate (5 × 20).
Plan the number of sponsored positions and candidates accordingly.

* **Latency**: Because the calls to the retail media network and Coveo must be sequential, the total latency is the sum of both calls.
Apply a strict timeout on the retail media network call to minimize the impact on the end-user experience.

* **Grouping compatibility**: If product grouping is configured on your interface, sponsoring a product doesn't force the retrieval of its complete group.
Only organically retrieved child products are folded under the sponsored position.

## Related pages

* [Relevance-Aware Sponsored Product pin rules for search](https://docs.coveo.com/en/q2pf0033/)

* [Relevance-Aware Sponsored Product pin rules for product listing pages](https://docs.coveo.com/en/pakd0058/)

* [Use the Commerce API directly](https://docs.coveo.com/en/p5je0317/)