Requesting a Substitution Ad

What Are Substitution Ads?

Substitution Ads are an opportunity for retailers to monetise their outgoing substitutions. Citrus streamlines the substitution process for advertisers and takes the targeting and measurement to a new level. At the click of a button advertisers are able to get their product into the hands of potential customers in order for them to “try before they buy”. This becomes especially important for advertisers when they release new products. Getting the product in front of a potential customer to experience the product first hand, could be the difference between making a sale or not.

The Context

In order to request Substitution Ads, you must provide a context.

An example of a context is shown below. In this example, the type of each kind of data is shown. For example, "string" means an alphanumeric string. number means a number like "1" or "950.49". Integer means a whole number, like "1" or "25".

A Simple Context

{
"catalogId": "string",
"customerId": "string",
"substitutedProductGtin": "string",
"pageType": "string",
"currentCartItems": [
{
"gtin": "string",
"quantity": "number",
"regularUnitPrice": "number",
"totalOrderItemPriceAfterDiscounts": "number",
"adId": "string",
}
],
"maxNumberOfAds": "number",
}

A mock version can be seen below:

This mock version features a single item in an order. This particular item is targeted by a Substitution campaign and will return an item to add to the pick list.

{
"catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
"customerId": "3g4e33rr45s3",
"substitutedProductGtin": "8511542010753_D4",
"pageType": "Substitution",
"currentCartItems": [
{
"gtin": "8431240103756_D4",
"quantity": "1",
"regularUnitPrice": "9.99",
"totalOrderItemPriceAfterDiscounts": "9.99",
}
],
"maxNumberOfAds": 1,
}

CurrentCartItems and substitutedProductGtin are required fields for Substitution Ads as these fields determine targeting

What Happens when an Ad Is Successfully Requested

When you successfully request an ad, you receive the following object. These ads are added to the retailer's pick list and added to the customer's order.

{
"ads": [
{
"id": "string",
"gtin": "string",
"expiry": "string",
}
],
}

A mock version can be seen below:

{
"ads": [
{
"id": "34558f9b-bbb9-49fb-93fe-3ad481cr443",
"gtin": "88560901388694",
"expiry": "2018-04-30T01:14:99.832ZD",
}
],
}

A Larger Cart Context

You will also encounter instances wherein your customers will have more that 1 item in their cart:

{
"catalogId": "string",
"customerId": "string",
"substitutedProductGtin": "string",
"pageType": "string",
"currentCartItems": [
{
"gtin": "string",
"quantity": "integer",
"regularUnitPrice": "number",
"totalOrderItemPriceAfterDiscounts": "number",
}
{
"gtin": "string",
"quantity": "integer",
"regularUnitPrice": "number",
"totalOrderItemPriceAfterDiscounts": "number",
}
{
"gtin": "string",
"quantity": "integer",
"regularUnitPrice": "number",
"totalOrderItemPriceAfterDiscounts": "number",
}
{
"gtin": "string",
"quantity": "integer",
"regularUnitPrice": "number",
"totalOrderItemPriceAfterDiscounts": "number",
}
],
"maxNumberOfAds": "number",
}

A mock version can be seen below:

This mock version features 4 items in an order. 3 of these items are targeted by Substitution Ad campaigns and will return 3 Ads.

{
"catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
"customerId": "3g4e33rr45s3",
"substitutedProductGtin": "8511542010753_D4",
"pageType": "Substitution",
"currentCartItems": [
{
"gtin": "8431240103756_D4",
"quantity": "1",
"regularUnitPrice": "99.99",
"totalOrderItemPriceAfterDiscounts": "99.99",
}
{
"gtin": "9234740103756_D4",
"quantity": "2",
"regularUnitPrice": "8.99",
"totalOrderItemPriceAfterDiscounts": "17.98",
}
{
"gtin": "1234840103242_D4",
"quantity": "1",
"regularUnitPrice": "27.99",
"totalOrderItemPriceAfterDiscounts": "22.99",
}
{
"gtin": "932454010213_D4",
"quantity": "3",
"regularUnitPrice": "14.99",
"totalOrderItemPriceAfterDiscounts": "44.97",
}
],
"maxNumberOfAds": 4,
}

What Happens when an Ad Is Successfully Requested

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

{
"ads": [
{
"id": "string",
"gtin": "string",
"expiry": "string",
}
{
"id": "string",
"gtin": "string",
"expiry": "string",
}
{
"id": "string",
"gtin": "string",
"expiry": "string",
}
],
}

A mock version can be seen below:

{
"ads": [
{
"id": "34558f9b-bbb9-49fb-93fe-3ad481cr443",
"gtin": "88560901388694",
"expiry": "2018-04-30T01:14:99.832ZD",
}
{
"id": "34558f9b-bbb9-49fb-93fe-3a432x3r3",
"gtin": "82360901380192",
"expiry": "2018-04-30T01:14:99.832ZD",
}
{
"id": "34558f9b-bbb9-49fb-93fe-3ads78349j",
"gtin": "89261901348532",
"expiry": "2018-04-30T01:14:99.832ZD",
}
],
}

A Larger Complex Cart Context

You may also encounter instances wherein your customers will have items added to their cart that are a result of clicks to Product Listing Ads, in this case the adId will be a field within currentCartItems:

{
"catalogId": "string",
"customerId": "string",
"substitutedProductGtin": "string",
"pageType": "string",
"currentCartItems": [
{
"gtin": "string",
"quantity": "integer",
"regularUnitPrice": "number",
"totalOrderItemPriceAfterDiscounts": "number",
"adId": "string",
}
{
"gtin": "string",
"quantity": "integer",
"regularUnitPrice": "number",
"totalOrderItemPriceAfterDiscounts": "number",
}
{
"gtin": "string",
"quantity": "integer",
"regularUnitPrice": "number",
"totalOrderItemPriceAfterDiscounts": "number",
"adId": "string",
}
{
"gtin": "string",
"quantity": "integer",
"regularUnitPrice": "number",
"totalOrderItemPriceAfterDiscounts": "number",
}
{
"gtin": "string",
"quantity": "integer",
"regularUnitPrice": "number",
"totalOrderItemPriceAfterDiscounts": "number",
"adId": "string",
}
{
"gtin": "string",
"quantity": "integer",
"regularUnitPrice": "number",
"totalOrderItemPriceAfterDiscounts": "number",
"adId": "string",
}
{
"gtin": "string",
"quantity": "integer",
"regularUnitPrice": "number",
"totalOrderItemPriceAfterDiscounts": "number",
"adId": "string",
}
],
"maxNumberOfAds": "number",
}

A mock version can be seen below:

This mock version features 12 items in an order. 4 of these items are targeted by Substitution Ad campaigns and will return 4 Ads. Additionally, 5 items contain the adId field as they're the result of a clicked Product Listing Ad.

An order like this is an exemplar of a typical weekly office environment order. Adding substitutions to a cart like this can lead to long term purchasing habits by the customer.

{
"catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
"customerId": "3g4e33rr45s3",
"substitutedProductGtin": "8511542010753_D4",
"pageType": "Substitution",
"currentCartItems": [
{
"gtin": "8431240103756_D4",
"quantity": "1",
"regularUnitPrice": "99.99",
"totalOrderItemPriceAfterDiscounts": "99.99",
"adId": "543ed-453fs-e3sqw-233ed",
}
{
"gtin": "9234740103756_D4",
"quantity": "2",
"regularUnitPrice": "8.99",
"totalOrderItemPriceAfterDiscounts": "17.98",
}
{
"gtin": "1234840103242_D4",
"quantity": "1",
"regularUnitPrice": "27.99",
"totalOrderItemPriceAfterDiscounts": "22.99",
"adId": "213fe-453fs-e3sqw-3728e",
}
{
"gtin": "932454010213_D4",
"quantity": "3",
"regularUnitPrice": "14.99",
"totalOrderItemPriceAfterDiscounts": "44.97",
}
{
"gtin": "924440103240_D4",
"quantity": "2",
"regularUnitPrice": "17.99",
"totalOrderItemPriceAfterDiscounts": "35.98",
"adId": "91bs3-453fs-e3sqw-302nr",
}
{
"gtin": "1654840103452_D4",
"quantity": "12",
"regularUnitPrice": "4.99",
"totalOrderItemPriceAfterDiscounts": "59.88",
"adId": "3534w-453fs-e3sqw-zv5tz",
}
{
"gtin": "1029840103426_D4",
"quantity": "8",
"regularUnitPrice": "6.99",
"totalOrderItemPriceAfterDiscounts": "55.92",
"adId": "345er-453fs-e3sqw-534dc",
}
{
"gtin": "3534740103722_D4",
"quantity": "15",
"regularUnitPrice": "2.99",
"totalOrderItemPriceAfterDiscounts": "44.85",
}
{
"gtin": "9434740103923_D4",
"quantity": "15",
"regularUnitPrice": "0.99",
"totalOrderItemPriceAfterDiscounts": "14.85",
}
{
"gtin": "1824740103606_D4",
"quantity": "11",
"regularUnitPrice": "6.49",
"totalOrderItemPriceAfterDiscounts": "71.39",
}
{
"gtin": "1842740103343_D4",
"quantity": "2",
"regularUnitPrice": "4.22",
"totalOrderItemPriceAfterDiscounts": "8.44",
}
{
"gtin": "7654740103743_D4",
"quantity": "2",
"regularUnitPrice": "8.99",
"totalOrderItemPriceAfterDiscounts": "17.98",
}
],
"maxNumberOfAds": 4,
}

What Happens when an Ad Is Successfully Requested

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

{
"ads": [
{
"id": "string",
"gtin": "string",
"expiry": "string",
}
{
"id": "string",
"gtin": "string",
"expiry": "string",
}
{
"id": "string",
"gtin": "string",
"expiry": "string",
}
{
"id": "string",
"gtin": "string",
"expiry": "string",
}
],
}

A mock version can be seen below:

{
"ads": [
{
"id": "34558f9b-bbb9-49fb-93fe-3ad481cr443",
"gtin": "88560901388694",
"expiry": "2018-04-30T01:14:99.832ZD",
}
{
"id": "31458f9b-bbb9-49fb-93fe-3a432x3r3",
"gtin": "82360901380192",
"expiry": "2018-04-30T01:14:99.832ZD",
}
{
"id": "43258f9b-bbb9-49fb-93fe-3ads78349j",
"gtin": "89261901348532",
"expiry": "2018-04-30T01:14:99.832ZD",
}
{
"id": "34248f9b-bbb9-49fb-93fe-3ads783ji2",
"gtin": "3221901343212",
"expiry": "2018-04-30T01:14:99.832ZD",
}
],
}

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