This documentation outlines best practices for generating product ads in search, category, and broad display (home, checkout, special, and so on) placements. Implementing these strategies make your ads more relevant and targeted, enhancing user engagement and satisfaction. The enhancements include pagination, filtered searches, and location-based filtering for a personalized advertising approach.

To generate product ads using search and category placements, see the following topics:

Paginate Requests

Pagination is a technique used to manage large sets of data by dividing them into discrete pages or segments. In the context of generating product ads, pagination ensures that users are not overwhelmed by too many ads at once and that previously viewed ads are not redundantly served.

When you generate product ads, the response includes a memoryToken. This token helps in keeping track of which ads have already been served. By including this memoryToken in subsequent ad requests, you can ensure that previously served ads are excluded from the new ad response, enhancing the user experience by presenting fresh and relevant ads.

Initial Request: Generate product ads and receive a memoryToken in the response.
Subsequent Requests: Include the memoryToken in subsequent ad requests to exclude previously served ads from the response.

For more information, see the Pagination.

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.
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.
searchTerm	string, required for search placements	Term to search for within the catalog.
memoryToken	string, required	Token to exclude previously served ads.
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

In the following example, the initial ad request is for search placement with the term "chocolate." The memoryToken is included to ensure that previously served ads for the same search term and context are excluded from the response. The options object specifies the filtering mode, and maxNumberOfAds sets the limit for the number of ads to be generated in the response.

By leveraging pagination and memory tokens, you can provide a more dynamic and engaging ad experience for your users, avoiding redundancy and enhancing relevance.

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

Response Example

All product ad responses follow a standard JSON format. Product ads are returned in the ads array.

id: The ad ID used in impression and click reports.
gtin: The Global Trade Item Number for the product.
discount: Details about any discounts applicable to the ad.
- amount: Discount amount.
- minPrice: Minimum price for the discount.
- maxPerCustomer: Maximum number of items a customer can purchase with the discount.
expiry: The expiration date and time of the ad.
position: The position of the ad in the response payload. Always read and honor the position field to ensure fixed tenancy placements appear correctly.

{
    "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": [],
    "memoryToken":"85ykKVv-luDHMWLZx2d6xcPq6sF7CgkJCSJDb3VudGVyIjogIjIiLAoJCQkiQWRzIjogWwoJCQkJImRpc3BsYXlfV05VV0NwQkRKMUpKNm5wdVZSVExvOU40TUxzNE1UWTBOemt5TWc9PSIsCgkJCQkiZGlzcGxheV9MME5NUHRxNmdCcVFvREJOd3J0dE9UTGJoWk0xTVRFeU9UYzRPUT09IiwKCQkJCSJkaXNwbGF5XzlCcEpmdUpaWk9VXzgyaWpFM3VCczgxd3VVczRNekkwTnpVeE5nPT0iLAoJCQkJImRpc3BsYXlfcW1VU1p4TkpMQ0lqeWQwdTFJRDk0RmxVZ0pnNE16STBOelV4Tnc9PSIsCgkJCQkiZGlzcGxheV9oeHlFZktCUnRrNWlxMThMQzE1SDJHcEN3QjgxTVRFeU9UYzVNQT09IiwKCQkJCSJkaXNwbGF5X1NkcjFEcU5aUEFtcGh0Q1FIUndoYUxFT1B0RXhNamsxT1RJNE5BPT0iLAoJCQkJImRpc3BsYXlfeVlSai1qV2Ntc2ozNzhrel9PMm0yOVlwTjhJeE5EazNPRE00TXc9PSIsCgkJCQkiZGlzcGxheV9Xbm9NZGZuLTRTVmhxcF9xQzVvLWxoT0paNm8xTkRJeE1UUTROdz09IgoJCQldLAoJCQkiVFRMIjogMTYyODk4NTYwMAoJCX0="
}

When onboarding marketplace sellers, an additional sellerId field may appear in the ad response. This field is included only if the campaign's owning team has configured a seller ID in the Epsilon Retail Media UI.

Example with Seller ID

{
    "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",
            "sellerId": "2834-ascre-2wcr4",
            "discount": {
                "amount": 0,
                "minPrice": 0,
                "maxPerCustomer": 0
            },
            "expiry": "2021-05-12T04:17:50.400908257Z",
            "position": 2
        }
    ],
    "banners": [],
    "products": [],
    "memoryToken":"85ykKVv-luDHMWLZx2d6xcPq6sF7CgkJCSJDb3VudGVyIjogIjIiLAoJCQkiQWRzIjogWwoJCQkJImRpc3BsYXlfV05VV0NwQkRKMUpKNm5wdVZSVExvOU40TUxzNE1UWTBOemt5TWc9PSIsCgkJCQkiZGlzcGxheV9MME5NUHRxNmdCcVFvREJOd3J0dE9UTGJoWk0xTVRFeU9UYzRPUT09IiwKCQkJCSJkaXNwbGF5XzlCcEpmdUpaWk9VXzgyaWpFM3VCczgxd3VVczRNekkwTnpVeE5nPT0iLAoJCQkJImRpc3BsYXlfcW1VU1p4TkpMQ0lqeWQwdTFJRDk0RmxVZ0pnNE16STBOelV4Tnc9PSIsCgkJCQkiZGlzcGxheV9oeHlFZktCUnRrNWlxMThMQzE1SDJHcEN3QjgxTVRFeU9UYzVNQT09IiwKCQkJCSJkaXNwbGF5X1NkcjFEcU5aUEFtcGh0Q1FIUndoYUxFT1B0RXhNamsxT1RJNE5BPT0iLAoJCQkJImRpc3BsYXlfeVlSai1qV2Ntc2ozNzhrel9PMm0yOVlwTjhJeE5EazNPRE00TXc9PSIsCgkJCQkiZGlzcGxheV9Xbm9NZGZuLTRTVmhxcF9xQzVvLWxoT0paNm8xTkRJeE1UUTROdz09IgoJCQldLAoJCQkiVFRMIjogMTYyODk4NTYwMAoJCX0="
}

Filtered Searches

When a customer applies filters to their search, you can enhance the context of their query by using productFilters. This allows you to target ads more precisely based on specific categories or attributes. Below, we provide an example of how to filter by the category "Cupboard" and the dietary restriction "Gluten-free". This methodology can be adapted to any category or broad match placement.

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.
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.
searchTerm	string, required for search placements	Term to search for within the catalog.
productFilters	array, required	An array containing the category filters.
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 example request uses the HTTP POST method to send a JSON object to the specified endpoint. The productFilters array specifies that the search should be filtered by the category "Cupboard" and the dietary restriction "Gluten-free". The options object sets the filterMode to AndOr, allowing for a flexible combination of filters. The maxNumberOfAds field limits the number of ads displayed to three.

By following this structure, you can create targeted ad campaigns that are more relevant to the customer's search criteria, thereby enhancing the overall user experience.

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": "search",
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "searchTerm": "chocolate",
    "productFilters": [
     	 ["category:Cupboard"],["dietary:Gluten-free"]
    ],
    "options": {
   							 "filterMode": "AndOr"
 							 },
    "maxNumberOfAds": 3
}

Filter by Location

When synchronizing location filters in your catalog, you can extend your context to include the customer's store location in the productFilters. This feature allows you to target ads based on the specific store location, enhancing the relevance of the advertisements shown to the customer.

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.
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.
searchTerm	string, required for search placements	Term to search for within the catalog.
productFilters	array, required	An array containing the category filters.
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 example request uses the HTTP POST method to send a JSON object to the specified endpoint.

The productFilters array specifies that the search should be filtered by:
- Category: "Cupboard"
- Dietary restriction: "Gluten-free"
- Location: "Westenbury"
The options object sets the filterMode to AndOr, allowing for a flexible combination of filters.
The maxNumberOfAds field limits the number of ads displayed to three.

By following this structure, you can create targeted ad campaigns that are more relevant to the customer's search criteria, thereby enhancing the overall user experience.

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": "search",
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "searchTerm": "chocolate",
    "productFilters": [
     	 ["category:Cupboard"],["dietary:Gluten-free"],["location:Westenbury"]
    ],
    "options": {
   							 "filterMode": "AndOr"
 							 },
    "maxNumberOfAds": 3
}