Requesting a Home Page Product Ad

Home Page ads require a simple "context' to be sent to CitrusAd. A "context" is a bit of code that defines the conditions under which a product is shown to a customer.

Context:

Below are the values needed to generate a home page ad:

HTTP
cURL
HTTP
POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic your_api_key_here
{
"pageType": "Home",
"catalogId": "$MY_CATALOG_ID",
"maxNumberOfAds": number
}
cURL
curl -iX POST "$BASE_URL/v1/ads/generate" \
-H "accept: application/json" \
-H "content-type: application/json" \
-H "Authorization: Basic your_api_key_here" \
-d \
'{
"pageType": "Home",
"catalogId": "$MY_CATALOG_ID",
"maxNumberOfAds": number
}'

Exemplar Context

Here is an example of a context for the pageType "Home":

HTTP
cURL
HTTP
POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic 4ww25f70-b52s-40de-8f29-07b139b5cdc8
{
"pageType": "Home",
"catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
"maxNumberOfAds": 3
}
cURL
curl -iX POST "$BASE_URL/v1/ads/generate" \
-H "accept: application/json" \
-H "content-type: application/json" \
-H "Authorization: Basic 4ww25f70-b52s-40de-8f29-07b139b5cdc8" \
-d \
'{
"pageType": "Home",
"catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
"maxNumberOfAds": 3
}'

What Happens when an Ad Is Successfully Requested

When you successfully request an ad, you receive the following object:

HTTP
cURL
HTTP
HTTP/2 200
{
"ads": [
{
"id": "display_SEY2W7-VZzspoirbw4ANs-r-w6YyODk5MDQ5UA==",
"gtin": "2899049P",
"discount": {
"amount": 0,
"minPrice": 0,
"maxPerCustomer": 0
},
"expiry": "2019-12-10T01:46:07.516943179Z"
},
{
"id": "display_-hPcUdg5KUQ2sxhE6r0XVN3-iLY5ODkxNTY2UA==",
"gtin": "9891566P",
"discount": {
"amount": 0,
"minPrice": 0,
"maxPerCustomer": 0
},
"expiry": "2019-12-10T01:46:07.516948637Z"
},
{
"id": "display_aGULlK-E_yEiVZ_S_jH9qsH-KhYyOTAyNjIwUA==",
"gtin": "2902620P",
"discount": {
"amount": 0,
"minPrice": 0,
"maxPerCustomer": 0
},
"expiry": "2019-12-10T01:46:07.516953955Z"
}
],
"banners": [],
"products": []
}
cURL
{
"ads": [
{
"id": "display_SEY2W7-VZzspoirbw4ANs-r-w6YyODk5MDQ5UA==",
"gtin": "2899049P",
"discount": {
"amount": 0,
"minPrice": 0,
"maxPerCustomer": 0
},
"expiry": "2019-12-10T01:46:07.516943179Z"
},
{
"id": "display_-hPcUdg5KUQ2sxhE6r0XVN3-iLY5ODkxNTY2UA==",
"gtin": "9891566P",
"discount": {
"amount": 0,
"minPrice": 0,
"maxPerCustomer": 0
},
"expiry": "2019-12-10T01:46:07.516948637Z"
},
{
"id": "display_aGULlK-E_yEiVZ_S_jH9qsH-KhYyOTAyNjIwUA==",
"gtin": "2902620P",
"discount": {
"amount": 0,
"minPrice": 0,
"maxPerCustomer": 0
},
"expiry": "2019-12-10T01:46:07.516953955Z"
}
],
"banners": [],
"products": []
}

No customer information or cart items are necessary in this simple context. The simple context consists only of necessary filters.

The discount and products fields are legacy and can be ignored

Using Session Ids for Order Attribution

If you are planning on using sessionIds as your method of order attribution, you will need to send a sessionId in your ad generation requests:

HTTP
cURL
HTTP
POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic your_api_key_goes_here
{
"pageType": "Home",
"catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
"sessionId": "23dn3923-323d",
"maxNumberOfAds": 3
}
cURL
curl -iX POST "$BASE_URL/v1/ads/generate" \
-H "accept: application/json" \
-H "content-type: application/json" \
-H "Authorization: Basic your_api_key_goes_here" \
-d \
'{
"pageType": "Home",
"catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
"sessionId": "23dn3923-323d",
"maxNumberOfAds": 3
}'

If you are unsure of the strings displayed on this page. Take a look at the Reference page.