Skip to content

API Integration for Retail Media Banners

Retail Media banners are campaign creatives that Hello Retail injects directly into your Search, Product Recommendations, and Pages results, alongside the regular products. The API marks each injected item with isBanner: true, so your frontend can tell banners and products apart and render each one correctly.

If you're using one of our managed solutions (Search, Recommendations, or Pages served as rendered HTML), see the template integration guide instead. It covers the Liquid and CSS changes needed there. This page covers integrating banners into a custom frontend, built directly against the JSON APIs.

Banners can be returned by any of the three APIs that support Retail Media: Search, Product Recommendations, and Pages. No extra parameters are required to request them: if a Retail Media campaign targets the request you're making, its banner is included in results alongside the products. While testing a campaign, you can pass includeRetailMediaInReview: true at the top level of the request to also see campaigns that are still in the review state. They still only appear where their targeting rules say they should.

Request Format

Requesting banners doesn't require any special parameters. A normal product request is enough. For example, a Search request:

{
  "query": "*",
  "key": "b8e5d3ea-f70d-47e1-9029-ab504596b352",
  "format": "json",
  "deviceType": "DESKTOP",
  "products": {
    "count": 10
  }
}

Response Structure

When a campaign matches, its banner is inserted into products.results at whatever position the campaign is configured for, so you don't need to place it yourself. Check isBanner on each item in results to tell banners apart from products: it's true on banners and absent on regular products.

Here's an example response containing one banner:

{
"query": "*",
"products":{
"start": 0,
"requestedCount": 10,
"returnedCount": 10,
"totalCount": 12,
"results": [
      {
        "isBanner": true,
        "retailMediaCampaignId": "68148f8003b5bc24b142b718",
        "description": "aa",
        "id": "68148f8003b5bc24b142b719",
        "title": "Forsiden - Det er fedt",
        "trackingCode": "ps-...|b-...|...",
        "url": "https://woocommerce.test/#...",
        "bannerImages": {
          "wide": {
            "altText": "_9780060289003.jpg",
            "width": 300,
            "height": 200,
            "url": "https://banners-test.helloretailcdn.com/.../300x200.jpeg"
          },
          "tall": {
            "altText": "_9780060289003.jpg",
            "width": 200,
            "height": 300,
            "url": "https://banners-test.helloretailcdn.com/.../200x300.jpeg"
          }
        }
      }
    ]
  }
}

Available properties on a banner item:

Name Type Description
isBanner Boolean Always true on a banner item. Use this to distinguish banners from products when rendering results.
id String ID of this banner.
retailMediaCampaignId String ID of the Retail Media campaign that produced this banner. Useful if you need to correlate the item with campaign data elsewhere.
title String Title configured for the campaign in My Hello Retail.
description String Description configured for the campaign in My Hello Retail.
url String The link the banner should point to, with a tracking fragment appended. Use this directly as the href: clicking it is tracked automatically the same way a product click is. See click tracking.
trackingCode String Opaque tracking code for this banner. Pass it to trackClick if you're tracking clicks manually instead of relying on the url fragment. Treat it as an opaque string; don't try to construct or parse it yourself.
bannerImages Object One entry per image size configured for this campaign, keyed by the size's name. See below.

The keys under bannerImages (wide and tall in the example above) are the size names you set up for the banner in My Hello Retail. Name them descriptively, since your template code will reference them directly. Each size contains:

Name Type Description
url String URL of the image for this size.
width Number Width of the image, in pixels.
height Number Height of the image, in pixels.
altText String Alt text for the image.

Rendering banners

Since a banner item can appear anywhere in products.results, render your result list the same way regardless of item type, and branch on isBanner inside that loop:

function renderResultItem(item) {
  if (item.isBanner) {
    return renderBanner(item);
  }
  return renderProduct(item);
}

renderBanner picks the right entry out of bannerImages for the slot it's rendering into (for example item.bannerImages.wide.url for a wide tile) and points the link at item.url.

Tracking

Banners are tracked exactly like products: the url field already has a tracking fragment appended, so if you link to it directly, clicks are tracked automatically once the Hello Retail script sees the fragment. If you handle click tracking manually, call trackClick with the banner's trackingCode, the same way you would for a product. See click tracking for the full mechanics of both approaches.