Partner API

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 CitrusAd's product ads.

⚠

️ ️Here before early October 2022?

We've updated our documentation in advance of some changes expected to rollout to production in early August. If you're reviewing our documentation beforehand, you might notice the token not returning - that's because it's not there yet!

As this is in active development, this is subject to change at CitrusAd's discretion.

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

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, CitrusAd will exclude any previously served ads to the customer if the ad contextincluding the sessionId are identical to the token's request.

How does it work?

When CitrusAd receives a memoryToken in the ad request, any previously served ads for an identical context 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 CitrusAd 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 CitrusAd (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 CitrusAd 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, CitrusAd will exclude all 15-20 ads previously served to you in the subsequent ad response.

Example request flow

Frequently asked questions

Can a retailer maintain a token across the entire customer journey?

No, CitrusAd check on our end if the ad requests matched the token's request. The retailer won't be able to take the token across multiple unique customer searches such as making different search requests.

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

No, if CitrusAd 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 happens when you are out of ads to serve such as page 5-10?

In this case, by default CitrusAd will not serve ads as we are out of ads to serve to the customer. If required, CitrusAd can configure that the order is restarted from page 1 when out of ordered ads.

What if I send a memoryToken and it is malformed?

CitrusAd will ignore the token and process the request as if it is a onormal request.