Partner API
API Reference

Pagination

Improve your customer experience when browsing multiple pages. When generating product ads, you will receive a memoryToken that can be sent in subsequent requests to exclude previously served ads.

🚧

Product Ads Only!

This capability is only currently supported for Epsilon Retail Media's product ads.

How to implement pagination on your site?

When generating product ads, in the response you will receive a memoryToken.

{
    "ads": [
        {
            "id": "display_3rGiryPskhQusmsf43nghbQwnqo3NzMzNjU3",
            "gtin": "7733657",
            "discount": {
                "amount": 0,
                "minPrice": 0,
                "maxPerCustomer": 0
            },
            "expiry": "2021-05-12T04:17:50.400917769Z",
            "position": 1
        }
    ],
    "banners": [],
    "products": [],
    "memoryToken":"85ykKVv-luDHMWLZx2d6xcPq6sF7CgkJCSJDb3VudGVyIjogIjIiLAoJCQkiQWRzIjogWwoJCQkJImRpc3BsYXlfV05VV0NwQkRKMUpKNm5wdVZSVExvOU40TUxzNE1UWTBOemt5TWc9PSIsCgkJCQkiZGlzcGxheV9MME5NUHRxNmdCcVFvREJOd3J0dE9UTGJoWk0xTVRFeU9UYzRPUT09IiwKCQkJCSJkaXNwbGF5XzlCcEpmdUpaWk9VXzgyaWpFM3VCczgxd3VVczRNekkwTnpVeE5nPT0iLAoJCQkJImRpc3BsYXlfcW1VU1p4TkpMQ0lqeWQwdTFJRDk0RmxVZ0pnNE16STBOelV4Tnc9PSIsCgkJCQkiZGlzcGxheV9oeHlFZktCUnRrNWlxMThMQzE1SDJHcEN3QjgxTVRFeU9UYzVNQT09IiwKCQkJCSJkaXNwbGF5X1NkcjFEcU5aUEFtcGh0Q1FIUndoYUxFT1B0RXhNamsxT1RJNE5BPT0iLAoJCQkJImRpc3BsYXlfeVlSai1qV2Ntc2ozNzhrel9PMm0yOVlwTjhJeE5EazNPRE00TXc9PSIsCgkJCQkiZGlzcGxheV9Xbm9NZGZuLTRTVmhxcF9xQzVvLWxoT0paNm8xTkRJeE1UUTROdz09IgoJCQldLAoJCQkiVFRMIjogMTYyODk4NTYwMAoJCX0="
}

When a customer is navigating to the next page, you should send this token in your next ad request.

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    
}

Using this token, Epsilon Retail Media will exclude any previously served ads to the customer if the sessionId are identical to the token's request.

🚧

Standard Integration!

This capability is only currently supported for Epsilon Retail Media's product ads.

How does it work?

When Epsilon Retail Media receives a memoryToken in the ad request, any previously served ads for the sessionId will be excluded from the ad response. This ensures a wider variety of ads served back to your customer on a multi-page journey.

When this token does not exist on the request, ad generation will be done as per current process with no exclusions applied. A token will always be provided after ad generation for a retailer to opt into utilising.

The memory token contains encoded information that allows Epsilon Retail Media to determine the ads that have been served previously (either in a single request, or over a period of multiple chained requests).

In the event of an irrelevant token being sent to Epsilon Retail Media (such as a different context), ads are returned as if no token was provided in the ad request.

⚠

️ Do you request more ads than served to your website?

If you're a retailer that requests more ads from Epsilon Retail Media than is served to your customer, you may not receive many ads on subsequent pages. If you request 15 ads and only serve 4 to your customer, when receiving the memoryToken, Epsilon Retail Media will exclude all 15-20 ads previously served to you in the subsequent ad response.

Example request flow

Frequently asked questions

Can I use this token across multiple customer searches to exclude products on the larger customer journey?

No, if Epsilon Retail Media receive an ad request that does not match the token's ad request, it is ignored and ads are generated as if there was no token provided.

What if I send a memoryToken and it is malformed?

Epsilon Retail Media will ignore the token and process the request as if it is a normal request.

How many pages can I paginate for?

By default, this is 5, this is the best balance of performance and saturation that Epsilon Retail Media has seen across multiple clients.

As of Epsilon Retail Media's release 39.0, this can be configured via your Technical Account Manager.

What happens when you are out of ads to serve such as page 5-10 on the default configuration?

The memoryToken is configured on Epsilon Retail Media's side to store ads from the number of pages in the configuration. For example, if the configuration is the default of 5 pages, Epsilon Retail Media will begin re-serving ads from page 7.

Pagination request 6 (page 6): the memoryToken contains information on the previous 5 pages' ads, therefore no ads from the previous 5 pages will be served.

Pagination request 7 (page 7): the ads from page 1 are eligible to be served.

What happens if I am out of ads before page 5 on the default configuration?

If for example, by page 3 you are out of ads, we will begin serving ads by page 7, as we store the total number of pages in the configuration as the previously served ads that shouldn't be served again.