This document provides a comprehensive guide on how to generate product advertisements based on specified search criteria. Each API request must include details about the context, such as:

• Placement
• Catalog ID
• Customer ID
• Session ID
• Search term
• 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 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.

• Exact Match:
  • Targets search terms that exactly match your keywords.
  • Example: If your keyword is "blue running shoes," your ad will only appear for users who type "blue running shoes" in that exact order without any other words.
• Phrase Match:
  • Targets search terms that exactly match your keywords.
  • Your ad can appear for searches that include additional words before or after the phrase.
  • Example: If your keyword is "blue running shoes," your ad will only appear for users who type "blue running shoes" in that exact order without any other words.
  • For more information, see Phrase match search terms.
• Negative Search Terms:
  • Excludes specific words or phrases from your campaign.
  • Prevents your ads from appearing in unrelated searches.
  • Example: Adding "used" as a negative term for a new car ad avoids displaying it to those seeking used cars.

Fetch API Keys and Base URL

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

2. 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:

Request Example

This request is used to generate up to 3 ads that are relevant to the search term chocolate. These ads will be placed in the search results for a specific customer (customerId: "wertg5432a") and session (sessionId: "ec9-4e07-881d-3e9"). The ads will be generated from the catalog identified by catalogId: "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b", with additional filtering options specified (filterMode: "AndOr").

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": "search",
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "searchTerm": "chocolate",
    "options": {
   						 "filterMode": "AndOr"
 							 },
    "maxNumberOfAds": 3    
}

Response Example

📘

When you receive product ad responses, the response will typically include product codes, such as GTINs in this example. Retailers need to use the product codes provided in the ad responses to look up the necessary metadata for displaying the products.

In this example, the "gtin": "024100191345" is the product code. Retailers will use this GTIN to identify and display the specific sponsored product.

{
    "ads": [
        {
            "id": "display_QqHaKRrKlFm1Wxr9c_DXJN4HSE3NzMzNjM2",
            "gtin": "7733636",
            "discount": {
                "amount": 0,
                "minPrice": 0,
                "maxPerCustomer": 0
            },
            "expiry": "2021-05-12T04:17:50.400902957Z",
            "position": 1
        },
        {
            "id": "display_NzsHqP0_iQedlo9VnrO2vqkwi_k3NzMzNjI4",
            "gtin": "7733628",
            "discount": {
                "amount": 0,
                "minPrice": 0,
                "maxPerCustomer": 0
            },
            "expiry": "2021-05-12T04:17:50.400908257Z",
            "position": 2
        },
        {
            "id": "display_xNeShqidaMuEqiJ0zNdt-Gzygjs3NzE0MTA3",
            "gtin": "7714107",
            "discount": {
                "amount": 0,
                "minPrice": 0,
                "maxPerCustomer": 0
            },
            "expiry": "2021-05-12T04:17:50.400912929Z",
            "position": 3
        },
        {
            "id": "display_3rGiryPskhQusmsf43nghbQwnqo3NzMzNjU3",
            "gtin": "7733657",
            "discount": {
                "amount": 0,
                "minPrice": 0,
                "maxPerCustomer": 0
            },
            "expiry": "2021-05-12T04:17:50.400917769Z",
            "position": 4
        }
    ],
    "banners": [],
    "products": [],
}

Next Steps

• Generate Product Ads Using Category Placements
• Optimize Ad Targeting