Partner API

Ad generation filtering

When requesting ads, you should aim to support your customer's filtering by brand, categories, dietary restrictions, and more. If your e-commerce site supports filtering that uses the and/or functionality, CitrusAd can support this with the additional filterMode parameter in your request.

There are two types of filtering, as outlined below.

andOr filtering (recommended)

andOr filtering is useful for contexts where the user has filtered deep in their search. It allows simpler context formatting, while still supporting deep filtering. This method follows the structure outlined below:

"productFilters": [
     [ "" OR "" ] AND [ "" OR "" ] AND [ "" OR "" ] 
    ],
    "options": {
     "filterMode": "AndOr"
    },

An example request looks like the following:

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",
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "productFilters": [
     	 ["category:bread"],
    	 ["brand:brandA","brand:brandB"],
    	 ["price:below $10"],
    	 ["nutrition:organic","nutrition:vegan"]
    ],
    "options": {
   							 "filterMode": "AndOr"
 							 },
    "maxNumberOfAds": 3
}

This approach is typically easier for retailers to chain requests by type when customers filter deep into their searches.

🚧

You must specify the filterMode of andOr for this functionality to work correctly.

orAnd filtering (default mode)

The default method of filtering product filters follows the structure outlined below:

"productFilters": [
     [ "" AND "" ], OR [ "" AND "" ], OR [ "" AND "" ] 
    ],
    "options": {
     "filterMode": "OrAnd"
    },

The same example presented above would be sent as a request like the below:

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",
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "productFilters": [
     	 ["category:bread","brand:brandA","price:below $10","nutrition:organic"],
     	 ["category:bread","brand:brandB","price:below $10","nutrition:organic"],
     	 ["category:bread","brand:brandA","price:below $10","nutrition:vegan"],
     	 ["category:bread","brand:brandB","price:below $10","nutrition:vegan"],       
    ],
    "options": {
   							 "filterMode": "OrAnd"
 							 },
    "maxNumberOfAds": 3
}

📘

You don’t need to specify a filterMode of orAnd for this functionality, as it is the default behaviour.