Generate banner X ads for different placements
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:
Log into your Epsilon's Retail Media team account.
Navigate to the top right of the page and click on the drop-down menu.
Select Integration Settings, from the drop-down menu.
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:
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:
Category placements
Category placements require productFilters to be specified in the request. The example below shows where you would send the category filters:
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:
As additional categories are perused, you need to update your API call accordingly.
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:
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.
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:
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.
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.
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.
Video ads
If a campaign has video ads configured, the response includes an admobject as can be seen below:
Companion products
If a campaign has companion products configured, the response includes a companionProductsarray of objects as can be seen below::
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.
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.
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.