Generate Product Ads Using Category Placements
This document provides a comprehensive guide on how to generate product advertisements based on specified categories. Each API request must include details about the context, such as:
- Customer ID
- Session ID
- Placement
- Catalog ID
- Product filters
- The maximum number of ads to display
Prerequisites
You must complete the following steps before you start requesting product ads for search placement.
Add Product Catalogs
Ensure that your products have been added to your catalogs and synced with the Epsilon Retail Media Platform.
Create a Campaign and Configure Categories
Ensure that you have created a campaign and configured categories. For more details, refer to Step 4: Configure Target Criteria.
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 for Category Placements
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. To specify category placements, the productFilters
must be included in the request body.
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. |
placement | string, required | Context in which the ad is displayed (e.g., "category"). Set to "category" for category placements. |
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. |
productFilters | array, required | An array containing the category filters. |
maxNumberOfAds | integer, required | Maximum number of ads to display. |
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
The JSON request is used to specify a category placement for ads related to the "Cupboard/Snacks" category. It includes the customer ID, session ID, catalog ID, filtering options, and sets the maximum number of ads to 3.
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",
"dtmCookieId": "AAAF8xLBTA968AB6TOthAAAAAAE",
"placement": "category",
"catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
"productFilters": [
["category:Cupboard/Snacks"]
],
"options": {
"filterMode": "AndOr"
},
"maxNumberOfAds": 3
}
Generate Ads for Cross-Sell Category Placements
Cross-sell category placements are similar to regular category placements but are specifically used to target ads for cross-selling products. In a cross-sell scenario, you aim to recommend complementary products based on the current category the user is browsing.
You should specify the exact category for which you want to generate ads. This category is typically the one displayed on the current page the user is browsing.
Request Example
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",
"dtmCookieId": "AAAF8xLBTA968AB6TOthAAAAAAE",
"catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
"productFilters": [
["category:Cupboard/Snacks"]
],
"options": {
"filterMode": "AndOr"
},
"maxNumberOfAds": 3
}
Merge Organic and Cross-Sell Category Targeting
If you aim to combine organic ads (ads relevant to the category being viewed) and cross-sell ads (ads for related categories or products) into a single ad placement, you will need to manage this integration yourself. This involves writing the logic to merge and display both types of ads together.
Best Practices:
- Organic Ads First: Show ads relevant to the current category (organic ads) first.
- Cross-Sell Ads Second: Then, display ads for related categories or products (cross-sell ads) after the organic ads.
Best Practices for Category-Based Ad Targeting
When users navigate through different categories, it is crucial to update your API call to reflect the current category being viewed. This ensures that the ads displayed remain relevant to the user's browsing context.
It is recommended to send the most specific (lowest level) category in your ad request to Epsilon Retail Media platform. Targeting the deepest category level provides more relevant and precisely targeted ads for the user.
Example Scenario
A user starts browsing in a general category and then navigates to a more specific subcategory.
Initial API Call
When the user is browsing "Home" category:
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",
"dtmCookieId": "AAAF8xLBTA968AB6TOthAAAAAAE",
"placement": "category",
"catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
"productFilters": [
["category:Home"]
],
"options": {
"filterMode": "AndOr"
},
"maxNumberOfAds": 3
}
Updated API Call
When the user navigates to the "Home > Furniture" subcategory:
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",
"dtmCookieId": "AAAF8xLBTA968AB6TOthAAAAAAE",
"placement": "category",
"catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
"productFilters": [
["category:Home/Furniture"]
],
"options": {
"filterMode": "AndOr"
},
"maxNumberOfAds": 3
}
Final API Call
When the user further navigates to the "Home > Furniture > Chairs" subcategory:
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",
"dtmCookieId": "AAAF8xLBTA968AB6TOthAAAAAAE",
"placement": "category",
"catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
"productFilters": [
["category:Home/Furniture/Chairs"]
],
"options": {
"filterMode": "AndOr"
},
"maxNumberOfAds": 3
}
By updating the API call to reflect the most specific category the user is browsing, you ensure that the ads served are highly relevant. Instead of specifying a chained request across multiple category levels (L1 + L2 + L3), it is recommended to specify the deepest (L3) category level.
Next Steps
Updated 5 months ago