Integrate a retail media network for sponsored products

This is for:

Developer

When using Relevance-Aware Sponsored Products, merchandisers can reserve positions for sponsored products in the Coveo Merchandising Hub (CMH). 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 receives one API response with sponsored products already merged into the organic results, respecting active facets, page size, and sorting.

Important

Contact your Coveo representative to enable Relevance-Aware Sponsored Products in your Coveo organization.

How the integration works

The integration follows a sequential flow:

  1. Your storefront 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.

  2. Your storefront passes the list of product IDs to the Coveo Commerce API in the Search or Listings endpoint using the pinnedProducts parameter.

  3. Coveo processes the candidate list against the reserved sponsored positions (as defined in the CMH when setting up Relevance-Aware Sponsored Products for search and for product listing pages). 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.

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

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:

[
  {"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 or Listings endpoint. The pinnedProducts parameter accepts an array of product IDs, sorted by priority (first ID has highest priority).

Sample search request with pinnedProducts:

{
  "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:

{
  "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"
}
Tip
Leading practice

Use the queryPinned attribute to render a visual indicator (such as a "Sponsored" label) on the storefront, so that users can distinguish sponsored products from organic results.

Limitations

  • Pin rule limits: Each Coveo organization 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.