This document provides a comprehensive guide on how to generate banner X advertisements for different placement types. Banner X ads are generated on /bannerx endpoint. All banner X requests require the contentStandardId and the bannerSlotIds you are requesting ads for. Each API request must also include details about the context, such as:

Placement
Catalog ID
Customer ID
Session ID
Search term
The maximum number of ads to display

Search placement

Prerequisites

You must complete the following steps before you start requesting banner X ads for search placement.

1. Add product catalogs

Ensure that your products have been added to your catalogs and synced with the Epsilon Retail Media Platform. For more information, see Introduction to Catalogs and Products.

2. Create a campaign and configure search terms

Ensure that you have created a campaign and configured search terms. For more details, refer to Step 4b: Configure search terms. Define the search terms that you want to target (include and exclude) for your product ads. You can specify exact match, phrase match, and negative search terms for your ads.

3. Fetch API keys and base URL

You must have a valid API key. To fetch the API keys, do the following:
1. Log into your Epsilon's Retail Media team account.
2. Navigate to the top right of the page and click on the drop-down menu.
3. Select Integration Settings, from the drop-down menu.
4. Click on the API Key tab. Your secret API key is initially hidden. To view it, click on the Show button. Once it becomes visible, copy your secret API key. Use this key for making API calls.
You must have the Base URL for the API endpoint. For example, https://staging-test.citrusad.com/v1/ads/generate HTTP/1.1. Check with your Technical Account Manager for the Base URL.

Generate Ads

Perform the following steps to generate product ads.

HTTP Request

Endpoint: /v1/ads/generate

Method: POST

Headers:

accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>

Request Parameters

The request body should be a JSON object containing the following fields:

Object	Type	Description
customerId	string, required	Unique identifier for the customer. This is provided by your retailer.
sessionId	string, required	Unique identifier for the session. This is required for the attribution and provided by the retailer.
contentStandardId	string, required	The content standard ID for your banner X.
bannerSlotIds	string, required	The slot ID of your banner X.
placement	string, required	Context in which the ad is displayed (e.g., "search").
catalogId	string, required	Unique identifier for the product catalog from which products are being filtered. You can get the catalogID from the Epsilon's Retail Media UI or from the retailer.
maxNumberOfAds	integer, required	Maximum number of ads to display. When requesting banner x ads, you're able to specify the maximum number of banners you would like to receive per banner slot. You can control this with the `maxNumberOfAds` parameter.
searchTerm	string, required for search placements	Term to search for within the catalog.
options	object, optional	Additional options such as filtering modes `AndOr`. If specified, the system will use both "AND" and "OR" conditions to narrow down the search results.

Request example

Search placements are typically the easiest to request. They require a searchTerm to be specified in the request, like the example below:

POST $BASE_URL/v1/ads/bannerx HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
{
    "customerId": "wertg5432a",
    "sessionId": "ec9-4e07-881d-3e9", 
    "placement": "search",
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "searchTerm": "chocolate",
    "options": {
   						 "filterMode": "AndOr"
 							 },
    "contentStandardId": "c61941e2-1435-460b-9d2b-5d838e3dba9c",
    "bannerSlotIds": [
    {
      "slotId": "<SLOT_ID>",
      "maxNumberOfAds": 1
    },
    {
      "slotId": "<SLOT_ID>",
      "maxNumberOfAds": 2
    }
  ]
}

Category placements

Category placements require productFilters to be specified in the request. The example below shows where you would send the category filters:

POST $BASE_URL/v1/ads/bannerx HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
{
    "customerId": "wertg5432a",
    "sessionId": "ec9-4e07-881d-3e9", 
    "placement": "category",
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "productFilters": [
     	 ["category:Cupboard/Snacks"]
    ],
    "options": {
   							 "filterMode": "AndOr"
 							 },
    "contentStandardId": "fec2ab89-7a29-42b5-b58a-5675688b52d9",
    "bannerSlotIds": [
    {
      "slotId": "<SLOT_ID>",
      "maxNumberOfAds": 1
    },
    {
      "slotId": "<SLOT_ID>",
      "maxNumberOfAds": 2
    }
}

As additional categories are perused, you should update your API call accordingly.

Cross-sell category placements

Cross-sell category placements have a very similar request to category placements. You will want to specify the exact category you are requesting ads for. This is typically the page you are on. Specify the category in the productFilters of the request. The example below shows where you would send the category filters:

POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
{
    "customerId": "wertg5432a",
    "sessionId": "ec9-4e07-881d-3e9", 
    "placement": "category-cross-sell",
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "productFilters": [
     	 ["category:Cupboard/Snacks"]
    ],
    "options": {
   							 "filterMode": "AndOr"
 							 },
    "contentStandardId": "fec2ab89-7a29-42b5-b58a-5675688b52d9",
    "bannerSlots": [
           {
      "slotId": "<SLOT_ID>",
      "maxNumberOfAds": 1
    },
    {
      "slotId": "<SLOT_ID>",
      "maxNumberOfAds": 2
    }
    ],            
    "maxNumberOfAds": 3
}

As additional categories are perused, you need to update your API call accordingly.

📘
Merging organic and cross-sell category targeting?
If you're looking to merge an organic and cross-sell category ad request into a single placement, you will need to implement merging and delivery logic to your customers. This is the integrator's responsibility, though Epsilon Retail Media is happy to be consulted.
In general, we advise that you show organic category ads, and position and category cross-sell advertisements after the organic placements.

Broad match placements

Broad placements such as home or checkout pages do not require any productFilters to be specified in the request. Any filters the retailer would like to specify (on offer, new, etc.) can be specified in the productFilters to ensure Epsilon Retail Media only serve ads within the requirements, like the example below:

POST $BASE_URL/v1/ads/bannerx HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
{
    "customerId": "wertg5432a",
    "sessionId": "ec9-4e07-881d-3e9", 
    "placement": "home",
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "productFilters": [
     	 []
    ],
    "options": {
   							 "filterMode": "AndOr"
 							 },
    "contentStandardId": "fec2ab89-7a29-42b5-b58a-5675688b52d9",
    "bannerSlotIds": [
    {
      "slotId": "<SLOT_ID>",
      "maxNumberOfAds": 1
    },
    {
      "slotId": "<SLOT_ID>",
      "maxNumberOfAds": 2
    }
}

Request enhancements

We advise you to consider the below enhancements to enhance your user experience.

Filtered searches

If your customer filters their search, you can extend your context to provide productFilters. Below is an example where the customer is filtering by the category "Cupboard" and the dietary restriction "Gluten-free". This same principle can be applied to any category or broad match placement.

POST $BASE_URL/v1/ads/bannerx HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
{
    "customerId": "wertg5432a",
    "sessionId": "ec9-4e07-881d-3e9", 
    "placement": "search",
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "searchTerm": "chocolate",
    "productFilters": [
     	 ["category:Cupboard"],["dietary:Gluten-free"]
    ],
    "options": {
   							 "filterMode": "AndOr"
 							 },
    "contentStandardId": "fec2ab89-7a29-42b5-b58a-5675688b52d9",
    "bannerSlotIds": [
    {
      "slotId": "<SLOT_ID>",
      "maxNumberOfAds": 1
    },
    {
      "slotId": "<SLOT_ID>",
      "maxNumberOfAds": 2
    }
}

Filtering by location

If you are synchronising location filters in your catalog, you can extend your context to provide the customer's store location in the productFilters, like the example below:

POST $BASE_URL/v1/ads/bannerx HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
{
    "customerId": "wertg5432a",
    "sessionId": "ec9-4e07-881d-3e9", 
    "placement": "search",
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "searchTerm": "chocolate",
    "productFilters": [
     	 ["category:Cupboard"],["dietary:Gluten-free"],["location:Westenbury"]
    ],
    "options": {
   							 "filterMode": "AndOr"
 							 },
    "contentStandardId": "fec2ab89-7a29-42b5-b58a-5675688b52d9",
    "bannerSlotIds": [
    {
      "slotId": "<SLOT_ID>",
      "maxNumberOfAds": 1
    },
    {
      "slotId": "<SLOT_ID>",
      "maxNumberOfAds": 2
    }
}

Banner X response

All responses follow the same JSON format. All content required to render the banner is provided in the response. If the banner does not have a component configured (such as no secondary hero image), Epsilon Retail Media will not serve the property.

{
    "ads": [
        {
            "contentStandardId": "c619d1e2-1435-460b-9d2b-5d838e3dba9c",
            "slotId": "<SLOT_ID>",
            "banners": [
                {
                    "citrusAdId": "shotgun__vW5pOojxDfN7T9VwaXWQLF2wKw3NzE0MTA3",
                    "citrusCampaignName": "CitrusAd-Example-Category-Banner-X-Ad-52793b405f1347b22e72a38c5a08699b",
                    "citrusContentStandardId": "c619d1e2-1435-460b-9d2b-5d838e3dba9c",
                    "citrusSlotId": "<SLOT_ID>",
                    "citrusExpiry": "2021-05-17T02:47:52.849995214Z",
                    "headingText": "Banner Advertisement for Magnum Double Ice Cream with a product image and shop now button",
                    "bannerText": "<strong>Magnum Double Ice Cream</strong>",
                    "bannerTextColour": "6e6c6c",
                    "ctaFlag": true,
                    "ctaText": "Shop now",
                    "ctaTextAccessibility": "for Magnum products",
                    "ctaLink": "https://www.tesco.com/groceries/en-GB/search?query=magnums",
                    "backgroundColour": "e1d6ac",
                    "heroImage": "https://cdn.flavedo.io/s/9b93e7f9-d747-4c8b-bcba-2357b280a3b3",
                    "heroImageAltText": "Magnums",
                    "tags": {},
                    "gtins": [
                        "7714107",
                        "7733636",
                        "7733657",
                        "7163379",
                        "7733628"
                    ],
                    "position": 1
                }
            ]
        },
        {
            "contentStandardId": "c619d1e2-1435-460b-9d2b-5d838e3dba9c",
            "slotId": "<SLOT_ID>",
            "banners": [
                {
                    "citrusAdId": "shotgun_kZp9yTCMm71vTo7iyQaK9I_YB09FUFYzNzBTQ0FO",
                    "citrusCampaignName": "milo-campaign-lakjsdf09kj",
                    "citrusContentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9",
                    "citrusSlotId": "<SLOT_ID>",
                    "citrusExpiry": "2021-05-17T02:47:52.849995214Z",
                    "headingText": "A banner for Milo with a product image and a shop now button",
                    "bannerText": "<strong>Try Milo Cereal</strong>",
                    "bannerTextColour": "48a94c",
                    "heroImage": "https://assets.imageurl.io/s/85d2d333-eed5-44d7-b131-8851d59f0574",
                    "heroImageAltText": "Milo product image",
                    "ctaFlag": true,
                    "ctaText": "Shop now",
                    "ctaTextAccessibility": "for Milo products",
                    "ctaLink": "retailer.com/everything/search/heritage%20mill?pageNumber=1",
                    "secondaryHeroImage": "https://assets.imageurl.io/s/85d2d333-eed5-44d7-b131-8m435c34r",
                    "secondaryHeroImageAltText": "Milo Logo",
                    "secondaryHeroMode": "landscape",
                    "backgroundColour": "895b5b",
                    "backgroundImage": "https://assets.flavedo.io/s/9c6fa248-c5ff-4341-9833-7e2b08464ada",
                    "backgroundImagePosition": "FILL",
                    "secondaryBackgroundImage": "https://assets.flavedo.io/s/9c6fa248-c5ff-4341-9833-7e2b08464ada",
                    "tags": {},
                    "gtins": [
                         "16309011",
                         "57312011",
                         "65250011"
                                ],
                    "position": 1
                }
            ]
        }
    ]
}

The id field is your Ad ID used in impression and click reports. Please refer to the reference for more information on each string.

Third-party tracking tags

For banner X ads, Epsilon Retail Media supports the passing of third-party tracking tags to the retailer. These tags are used by advertisers to verify their performance by a trusted third party.

Epsilon Retail Media support the tracking tags below:

DoubleVerify (Javascript and Image)
DCM Click
DCM Impression
IAS
Adform Impression
Adform click

If a campaign has a tracking tag configured, it will present as the relevant field in the trackingTags object below. Please note, if a campaign does not have a tag configured, the tagsand trackingTags object will remain empty.

{
    "ads": [
        {
            "contentStandardId": "c619d1e2-1435-460b-9d2b-5d838e3dba9c",
            "slotId": "<SLOT_ID>",
            "banners": [
                {
                    "citrusAdId": "shotgun__vW5pOojxDfN7T9VwaXWQLF2wKw3NzE0MTA3",
                    "citrusCampaignName": "CitrusAd-Example-Category-Banner-X-Ad-52793b405f1347b22e72a38c5a08699b",
                    "citrusContentStandardId": "c619d1e2-1435-460b-9d2b-5d838e3dba9c",
                    "citrusSlotId": "<SLOT_ID>",
                    "citrusExpiry": "2021-05-17T02:47:52.849995214Z",
                    "headingText": "Banner Advertisement for Magnum Double Ice Cream with a product image and shop now button",
                    "bannerText": "<strong>Magnum Double Ice Cream</strong>",
                    "bannerTextColour": "6e6c6c",
                    "ctaFlag": true,
                    "ctaText": "Shop now",
                    "ctaTextAccessibility": "for Magnum products",
                    "ctaLink": "https://www.tesco.com/groceries/en-GB/search?query=magnums",
                    "backgroundColour": "e1d6ac",
                    "heroImage": "https://cdn.flavedo.io/s/9b93e7f9-d747-4c8b-bcba-2357b280a3b3",
                    "heroImageAltText": "Magnums",
                    "tags": {},
                  	"trackingTags": {
                        "ADFORM_CLICK": "https://track.adform.net...",
                        "ADFORM_IMPRESSION": "<img src=\"https://track.adform.net...",
                        "DCM_CLICK": "https://ad.doubleclick.net/ddm/trackclk/...",
                        "DCM_IMPRESSION": "<IMG SRC=\"https://ad.doubleclick.net/ddm/trackimp/...",
                        "DV": "<script src=\"https://cdn.doubleverify.com/dvtp_src.js?ctx=...",
                        "DV_IMAGE": "<img src=\"https://tps.doubleverify.com/visit.jpg?ctx=..."
                    },
                    "gtins": [
                        "7714107",
                        "7733636",
                        "7733657",
                        "7163379",
                        "7733628"
                    ],
                    "position": 1
                }
            ]
        }
    ]
}

As Epsilon Retail Media is a server-to-server integration, third-party tracking tags require additional development by the retailer. Contact your Integration Program Manager (IPM) if you are looking to utilise this feature.

📘
tags object
For DoubleVerify (Javascript) and DCM tags, you may see the tags object populated as well. It is best practice to use the trackingTags response.

Video ads

If a campaign has video ads configured, the response includes an admobject as can be seen below:

{

  "ads": [

    {

      "contentStandardId": "c47c9ca2-ad3b-48cc-880b-e899c1661726",

      "slotId": "Top_Banner",

      "banners": [

        {

          "citrusAdId": "shotgun_8SvgA7OvvuwtZkkOKR0vr8AXMvQKFgoURmluZ2VybGltZTI2LWZkeHZxMjcSABoMCO30r70GEKPplJQCIgIIAQ==",

          "citrusCampaignName": "Ads:74-330-96832622ed499dafb3da8de8b76340a2",

          "citrusContentStandardId": "c47c9ca2-ad3b-48cc-880b-e899c1661726",

          "citrusSlotId": "Top_Banner",

          "citrusExpiry": "2025-02-12T01:33:33.579155107Z",

          "headingText": "recusandae 3205",

          "bannerText": "placeat 2825",

          "bannerTextColour": "ffffff",

          "ctaFlag": true,

          "ctaText": "CTA text",

          "ctaTextAccessibility": "call to action accessibility text",

          "ctaLink": http://citrusad.com ,

          "backgroundColour": "000000",

          "backgroundImage": https://dev3.flavedo.io./citrus/8de07ed9-60b4-4611-8bd5-3f1f0c0b6be4,

          "secondaryBackgroundImage": https://dev3.flavedo.io./citrus/b7a70785-1366-42c6-8134-c7fe47a30c34,

          "secondaryBackgroundImagePosition": "rightaligned",

          "heroImage": https://dev3.flavedo.io./citrus/26798ca9-1022-422d-9100-1a3687c88372,

          "heroImageAltText": "hero image alt text",

          "secondaryHeroImage": https://dev3.flavedo.io./citrus/c4ee18b4-bf51-44d7-9eb6-eeb1dc4c422f,

          "secondaryHeroImageAltText": "secondary hero image alt text",

          "secondaryHeroMode": "landscape",

          "tags": {},

          "additionalFields": [

            {

              "id": "text-1",

              "value": "sed 5731"

            }

          ],

          "gtins": [

            "Fingerlime26-fdxvq27",

            "Oranges5-qgxeb6",

            "Cherries9-adkoj11",

            "Incaberries20-ppscn21",

            "Banana14-simfk15"

          ],

          "sellerId": "seller_id_772_659",

          "position": 1,

          "metadata": {

            "advertiserInfo": {

             "advertiser": "Bob's advertising agency",

             "onBehalfOf": "Brand company inc"

            }

          },
          "adm": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<VAST version=\"4.0\">\n    <Ad id=\"1\">\n        <InLine>\n            <AdSystem>CitrusAd</AdSystem>\n            <Impression><![CDATA[https://integration.BASE-URL.citrusad.com/v1/resource/first-i/shotgun_2DbJUbTdlM3HFvLuF75YoA2FgpwKBQoDMTIzEgAaCwjHsuG_BhD7sqZzIgIIAQ==]]></Impression>\n            <ViewableImpression>\n                <Viewable><![CDATA[https://integration.BASE-URL.citrusad.com/v1/resource/first-i/shotgun_2DbJUbTdlM3HFvLuF75YoA2FgpwKBQoDMTIzEgAaCwjHsuG_BhD7sqZzIgIIAQ==]]></Viewable>\n                <NotViewable></NotViewable>\n                <ViewUndetermined></ViewUndetermined>\n            </ViewableImpression>\n            <AdTitle>VAST-4.0-Short-Intro.mp4</AdTitle>\n            <Creatives>\n                <Creative>\n                    <UniversalAdId idRegistry=\"http://citrusad.com \" idValue=\"VAST-4.0-Short-Intro.mp4\">VAST-4.0-Short-Intro.mp4</UniversalAdId>\n                    <Linear>\n                        <Duration></Duration>\n                        <MediaFiles>\n                            <MediaFile delivery=\"progressive\" type=\"video/mp4\" width=\"0\" height=\"0\" bitrate=\"0\" codec=\"\"><![CDATA[https://cdn.flavedo.io./citrus/VAST-4.0-Short-Intro.mp4]]></MediaFile>\n                            <Mezzanine><![CDATA[https://cdn.flavedo.io./citrus/VAST-4.0-Short-Intro.mp4]]></Mezzanine>\n                        </MediaFiles>\n                        <VideoClicks>\n                            <ClickTracking><![CDATA[https://integration.BASE-URL.citrusad.com/v1/resource/second-c/shotgun_2DbJUbTdlM3HFvLuF75YoA2FgpwKBQoDMTIzEgAaCwjHsuG_BhD7sqZzIgIIAQ==]]></ClickTracking>\n                            <ClickThrough><![CDATA[a/a-national/everything/browse]]></ClickThrough>\n                        </VideoClicks>\n                    </Linear>\n                </Creative>\n            </Creatives>\n        </InLine>\n    </Ad>\n</VAST>"      

       }

      ]

    }

  ]

}

Companion products

If a campaign has companion products configured, the response includes a companionProductsarray of objects as can be seen below::

{
  "ads": [
    {
      "contentStandardId": "c47c9ca2-ad3b-48cc-880b-e899c1661726",
      "slotId": "Top_Banner",
      "banners": [
        {
          "citrusAdId": "shotgun_8SvgA7OvvuwtZkkOKR0vr8AXMvQKFgoURmluZ2VybGltZTI2LWZkeHZxMjcSABoMCO30r70GEKPplJQCIgIIAQ==",
          "citrusCampaignName": "Ads:74-330-96832622ed499dafb3da8de8b76340a2",
          "citrusContentStandardId": "c47c9ca2-ad3b-48cc-880b-e899c1661726",
          "citrusSlotId": "Top_Banner",
          "citrusExpiry": "2025-02-12T01:33:33.579155107Z",
          "headingText": "recusandae 3205",
          "bannerText": "placeat 2825",
          "bannerTextColour": "ffffff",
          "ctaFlag": true,
          "ctaText": "CTA text",
          "ctaTextAccessibility": "call to action accessibility text",
          "ctaLink": http://citrusad.com,
          "backgroundColour": "000000",
          "backgroundImage": https://dev3.flavedo.io./citrus/8de07ed9-60b4-4611-8bd5-3f1f0c0b6be4,
          "secondaryBackgroundImage": https://dev3.flavedo.io./citrus/b7a70785-1366-42c6-8134-c7fe47a30c34,
          "secondaryBackgroundImagePosition": "rightaligned",
          "heroImage": https://dev3.flavedo.io./citrus/26798ca9-1022-422d-9100-1a3687c88372,
          "heroImageAltText": "hero image alt text",
          "secondaryHeroImage": https://dev3.flavedo.io./citrus/c4ee18b4-bf51-44d7-9eb6-eeb1dc4c422f,
          "secondaryHeroImageAltText": "secondary hero image alt text",
          "secondaryHeroMode": "landscape",
          "tags": {},
          "additionalFields": [
            {
              "id": "text-1",
              "value": "sed 5731"
            }
          ],
          "gtins": [
            "Fingerlime26-fdxvq27",
            "Oranges5-qgxeb6",
            "Cherries9-adkoj11",
            "Incaberries20-ppscn21",
            "Banana14-simfk15"
          ],
          "sellerId": "seller_id_772_659",
          "position": 1,
          "metadata": {
            "advertiserInfo": {
             "advertiser": "Bob's advertising agency",
             "onBehalfOf": "Brand company inc"
            }
          },
          “companionProducts”: [
            "Banana14-simfk15"
            "Oranges5-qgxeb6",
            "Incaberries20-ppscn21",
          ]
        }
      ]
    }
  ]
}

Marketplace sellerId

If onboarding marketplace sellers, you may see an additional sellerId per ad in the response. This will only appear if the team that owns the campaign being served has a seller ID configured in the UI. The example below shows one ad with a sellerId, one without.

{
    "ads": [
        {
            "contentStandardId": "c619d1e2-1435-460b-9d2b-5d838e3dba9c",
            "slotId": "<SLOT_ID>",
            "banners": [
                {
                    "citrusAdId": "shotgun__vW5pOojxDfN7T9VwaXWQLF2wKw3NzE0MTA3",
                    "citrusCampaignName": "CitrusAd-Example-Category-Banner-X-Ad-52793b405f1347b22e72a38c5a08699b",
                    "citrusContentStandardId": "c619d1e2-1435-460b-9d2b-5d838e3dba9c",
                    "citrusSlotId": "<SLOT_ID>",
                    "citrusExpiry": "2021-05-17T02:47:52.849995214Z",
                    "headingText": "Banner Advertisement for Magnum Double Ice Cream with a product image and shop now button",
                    "bannerText": "<strong>Magnum Double Ice Cream</strong>",
                    "bannerTextColour": "6e6c6c",
                    "ctaFlag": true,
                    "ctaText": "Shop now",
                    "ctaTextAccessibility": "for Magnum products",
                    "ctaLink": "https://www.retailer.com/groceries/en-GB/search?query=magnums",
                    "backgroundColour": "e1d6ac",
                    "heroImage": "https://cdn.flavedo.io/s/9b93e7f9-d747-4c8b-bcba-2357b280a3b3",
                    "heroImageAltText": "Magnums",
                    "tags": {},
                    "gtins": [
                        "7714107",
                        "7733636",
                        "7733657",
                        "7163379",
                        "7733628"
                    ],
                    "position": 1,
                    "sellerId": "1ben32-ss3d43-amea"
                }
            ]
        },
        {
            "contentStandardId": "c619d1e2-1435-460b-9d2b-5d838e3dba9c",
            "slotId": "<SLOT_ID>",
            "banners": [
                {
                    "citrusAdId": "shotgun_kZp9yTCMm71vTo7iyQaK9I_YB09FUFYzNzBTQ0FO",
                    "citrusCampaignName": "milo-campaign-lakjsdf09kj",
                    "citrusContentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9",
                    "citrusSlotId": "<SLOT_ID>",
                    "citrusExpiry": "2021-05-17T02:47:52.849995214Z",
                    "headingText": "A banner for Milo with a product image and a shop now button",
                    "bannerText": "<strong>Try Milo Cereal</strong>",
                    "bannerTextColour": "48a94c",
                    "heroImage": "https://assets.imageurl.io/s/85d2d333-eed5-44d7-b131-8851d59f0574",
                    "heroImageAltText": "Milo product image",
                    "ctaFlag": true,
                    "ctaText": "Shop now",
                    "ctaTextAccessibility": "for Milo products",
                    "ctaLink": "retailer.com/everything/search/heritage%20mill?pageNumber=1",
                    "secondaryHeroImage": "https://assets.imageurl.io/s/85d2d333-eed5-44d7-b131-8m435c34r",
                    "secondaryHeroImageAltText": "Milo Logo",
                    "secondaryHeroMode": "landscape",
                    "backgroundColour": "895b5b",
                    "backgroundImage": "https://assets.flavedo.io/s/9c6fa248-c5ff-4341-9833-7e2b08464ada",
                    "backgroundImagePosition": "FILL",
                    "secondaryBackgroundImage": "https://assets.flavedo.io/s/9c6fa248-c5ff-4341-9833-7e2b08464ada",
                    "tags": {},
                    "gtins": [
                         "16309011",
                         "57312011",
                         "65250011"
                                ],
                    "position": 1
                }
            ]
        }
    ]
}

Third-party tracking tags

Epsilon Retail Media supports the passing of third-party tracking tags to the retailer. These tags are used by advertisers to verify their performance by a trusted third party.

Epsilon Retail Media support the tracking tags below:

DoubleVerify
DCM Click
DCM Impression
IAS

If a campaign has a tracking tag configured, it will present as the relevant field in the tags object below. Please note, if a campaign does not have a tag configured, the tags object will remain empty.

{
    "ads": [],
    "banners": [
				{
            "id": "banner_XeemTeq59HapGSp4vccOYfBq_yvc3zMzNjM2",
            "contentStandardId": "fec2ab89-7a29-42b5-b58a-5675688b52d9",
            "slotId": "<SLOT_ID>",
            "imageUrl": "https://cdn.flavedo.io/s/-oW-C3cEViSSO2krWkwOBUXOhvUdhHOySx-YQLGZ1lA=",
            "linkUrl": "https://www.retailer.com/link",
            "altText": "Your local ice cream",
            "text": "",
            "gtins": [
                "7733628",
                "7714107",
                "7163379",
                "7733636",
                "7733657"
            ],
            "expiry": "2021-05-17T01:49:17.75503253Z",
            "tags": {
                "dv": "<script src=\"https://cdn.doubleverify.com/dvtp_src.js?ctx=919421&cmp=1074060503&sid=1073907024&plc=1075810393&adsrv=115&btreg=&btadsrv=&crt=&tagtype=&dvtagver=6.1.src\" type=\"text/javascript\"></script>",
                "dcmClick": "<script ..../>",
                "dcmImpression": "<script.... />",
                "ias": "<script.... />"            }
        }
				],
    "products": [],
     "memoryToken":"85ykKVv-luDHMWLZx2d6xcPq6sF7CgkJCSJDb3VudGVyIjogIjIiLAoJCQkiQWRzIjogWwoJCQkJImRpc3BsYXlfV05VV0NwQkRKMUpKNm5wdVZSVExvOU40TUxzNE1UWTBOemt5TWc9PSIsCgkJCQkiZGlzcGxheV9MME5NUHRxNmdCcVFvREJOd3J0dE9UTGJoWk0xTVRFeU9UYzRPUT09IiwKCQkJCSJkaXNwbGF5XzlCcEpmdUpaWk9VXzgyaWpFM3VCczgxd3VVczRNekkwTnpVeE5nPT0iLAoJCQkJImRpc3BsYXlfcW1VU1p4TkpMQ0lqeWQwdTFJRDk0RmxVZ0pnNE16STBOelV4Tnc9PSIsCgkJCQkiZGlzcGxheV9oeHlFZktCUnRrNWlxMThMQzE1SDJHcEN3QjgxTVRFeU9UYzVNQT09IiwKCQkJCSJkaXNwbGF5X1NkcjFEcU5aUEFtcGh0Q1FIUndoYUxFT1B0RXhNamsxT1RJNE5BPT0iLAoJCQkJImRpc3BsYXlfeVlSai1qV2Ntc2ozNzhrel9PMm0yOVlwTjhJeE5EazNPRE00TXc9PSIsCgkJCQkiZGlzcGxheV9Xbm9NZGZuLTRTVmhxcF9xQzVvLWxoT0paNm8xTkRJeE1UUTROdz09IgoJCQldLAoJCQkiVFRMIjogMTYyODk4NTYwMAoJCX0="
}

As Epsilon Retail Media is a server-to-server integration, third-party tracking tags require additional development by the retailer.

Digital Services Act

Epsilon Retail Media assists retailers in meeting their European Union (EU) Digital Services Act (DSA) obligations. The DSA establishes a unified set of rules across the EU, targeting the regulation of online content, transparent advertising, and disinformation. For more information, see Digital Services Act.

Example ad request

{
    "catalogId": "57a5318b-5349-46fd-80ed-fd2e0be15819",
    "contentStandardId": "c47c9ca2-ad3b-48cc-880b-e899c1661726",
    "bannerSlotIds": [
        {
            "slotId": "Top_Banner",
            "maxNumberOfAds": 1
        }
    ],
    "customerId": "velit3193",
    "placement": "broad-display-60e9699d-984f-4a80-9383-2e6dc7a68d03",
    "options": {
        "includeAdvertiserInfo": true
    }
}

Example ad response

{
  "ads": [
    {
      "contentStandardId": "c47c9ca2-ad3b-48cc-880b-e899c1661726",
      "slotId": "Top_Banner",
      "banners": [
        {
          "citrusAdId": "shotgun_8SvgA7OvvuwtZkkOKR0vr8AXMvQKFgoURmluZ2VybGltZTI2LWZkeHZxMjcSABoMCO30r70GEKPplJQCIgIIAQ==",
          "citrusCampaignName": "Ads:74-330-96832622ed499dafb3da8de8b76340a2",
          "citrusContentStandardId": "c47c9ca2-ad3b-48cc-880b-e899c1661726",
          "citrusSlotId": "Top_Banner",
          "citrusExpiry": "2025-02-12T01:33:33.579155107Z",
          "headingText": "recusandae 3205",
          "bannerText": "placeat 2825",
          "bannerTextColour": "ffffff",
          "ctaFlag": true,
          "ctaText": "CTA text",
          "ctaTextAccessibility": "call to action accessibility text",
          "ctaLink": "http://citrusad.com",
          "backgroundColour": "000000",
          "backgroundImage": "https://dev3.flavedo.io./citrus/8de07ed9-60b4-4611-8bd5-3f1f0c0b6be4",
          "secondaryBackgroundImage": "https://dev3.flavedo.io./citrus/b7a70785-1366-42c6-8134-c7fe47a30c34",
          "secondaryBackgroundImagePosition": "rightaligned",
          "heroImage": "https://dev3.flavedo.io./citrus/26798ca9-1022-422d-9100-1a3687c88372",
          "heroImageAltText": "hero image alt text",
          "secondaryHeroImage": "https://dev3.flavedo.io./citrus/c4ee18b4-bf51-44d7-9eb6-eeb1dc4c422f",
          "secondaryHeroImageAltText": "secondary hero image alt text",
          "secondaryHeroMode": "landscape",
          "tags": {},
          "additionalFields": [
            {
              "id": "text-1",
              "value": "sed 5731"
            }
          ],
          "gtins": [
            "Fingerlime26-fdxvq27",
            "Oranges5-qgxeb6",
            "Cherries9-adkoj11",
            "Incaberries20-ppscn21",
            "Banana14-simfk15"
          ],
          "sellerId": "seller_id_772_659",
          "position": 1,
          "metadata": {
            "advertiserInfo": {
             "advertiser": "Bob's advertising agency",
          "onBehalfOf": "Brand company inc"
            }
          }
        }
      ]
    }
  ]
}

Generate banner X ads for different placements

Search placement

Prerequisites

1. Add product catalogs

2. Create a campaign and configure search terms

3. Fetch API keys and base URL

Generate Ads

HTTP Request

Request Parameters

Request example

Category placements

Cross-sell category placements

📘
Merging organic and cross-sell category targeting?

Broad match placements

Request enhancements

Filtered searches

Filtering by location

Banner X response

Third-party tracking tags

📘
`tags` object

Video ads

Companion products

Marketplace sellerId

Third-party tracking tags

Digital Services Act

Example ad request

Example ad response

Search placement

Prerequisites

1. Add product catalogs

2. Create a campaign and configure search terms

3. Fetch API keys and base URL

Generate Ads

HTTP Request

Request Parameters

Request example

Category placements

Cross-sell category placements

📘Merging organic and cross-sell category targeting?

Broad match placements

Request enhancements

Filtered searches

Filtering by location

Banner X response

Third-party tracking tags

📘tags object

Video ads

Companion products

Marketplace sellerId

Third-party tracking tags

Digital Services Act

Example ad request

Example ad response

📘
Merging organic and cross-sell category targeting?

📘
`tags` object