The Post Checkout Banner Ad Context

What Are Post Checkout Banner Ads?

Post Checkout Banner Ads are an opportunity for retailers to monetise their website experience after a customer has completed their order. As customers are unlikely to remain on the retailer's site or create an additional order, it is heavily advised that this opportunity is opened to third parties to advertise their relevant banners.

The Context

In order to request Post Checkout Banner 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

POST $BASE_URL/v1/ads/generate HTTP/1.1 
accept: application/json
content-type: application/json
Authorization: Basic your_api_key_here
{
    "catalogId": "string",
    "customerId": "string",
    "pageType": "string",
    "currentCartItems": [
    {
            "gtin": "string=pa_id",
            "quantity": "number",
            "regularUnitPrice": "number",
            "totalOrderItemPriceAfterDiscounts": "number",
            "adId": "string",
    }
    ],
    "maxNumberOfAds": "number",
    "contentStandardId": "contentStandardId1",
    "bannerSlotIds": ["slotId1"],
    "sessionId": "String"
}

A mock version can be seen below:

This mock version features a single item in an order. This particular item is targeted by a Post Checkout Banner Ad campaign and will return a Banner Ad.

POST $BASE_URL/v1/ads/generate HTTP/1.1 
accept: application/json
content-type: application/json
Authorization: Basic 4ww25f70-b52s-40de-8f29-07b139b5cdc8
{
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "customerId": "3g4e33rr45s3",
    "pageType": "PostCheckout",
    "currentCartItems": [
    {
            "gtin": "catpref--8431240103756_D4",
            "quantity": "1",
            "regularUnitPrice": "99.99",
            "totalOrderItemPriceAfterDiscounts": "99.99",
    }
    ],
    "maxNumberOfAds": 1,
    "contentStandardId": "contentStandardId1",
    "bannerSlotIds": ["Post_Checkout8"],
    "sessionId": "23dn3923-323d (this is a generated id that you control which identifies a user’s session). Optional"
}

CurrentCartItems is a required field for Post Checkout Banner Ads as this field determines Banner targeting

What Happens when an Ad Is Successfully Requested

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

HTTP/2 200
{
    "ads": [ ],
    "banners": [
        {
            "id": "string",
            "slotId": "string",
            "imageUrl": "string",
            "linkUrl": "string",
            "altText": "string",
            "expiry": "string"
        }
    ]
}

A mock version can be seen below:

HTTP/2 200
{
    "ads": [ ],
    "banners": [
        {
            "id": "postcheckout_GPZmwLMUH9n0_zfZTfn8UcmAShRlZmx",
            "slotId": "Post_Checkout",
            "imageUrl": "https://assets.example.com/q/mdNYanp7zYVG6h4zYlSduXfadhNUctYG_9gsNlPHQ9t=",
            "linkUrl": "https://www.externalsite.com/landingpage-campaign652936600",
            "altText": "An image of XYZ subscription service with a limited offer and a Shop Now button.",
            "expiry": "2002-10-02T15:00:00.05Z"
        }
    ]
}

A Larger Cart Context

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

POST $BASE_URL/v1/ads/generate HTTP/1.1 
accept: application/json
content-type: application/json
Authorization: Basic your_api_key_here
{
    "catalogId": "string",
    "customerId": "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": "integer",
    "contentStandardId": "string",
    "bannerSlotIds": ["string"],
    "sessionId": "String"
}

A mock version can be seen below:

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

POST $BASE_URL/v1/ads/generate HTTP/1.1 
accept: application/json
content-type: application/json
Authorization: Basic 4ww25f70-b52s-40de-8f29-07b139b5cdc8
{
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "customerId": "3g4e33rr45s3",
    "pageType": "PostCheckout",
    "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,
    "contentStandardId": "contentStandardId1",
    "bannerSlotIds": ["Post_Checkout"],
    "sessionId": "23dn3923-323d (this is a generated id that you control which identifies a user’s session). Optional"
}

What Happens when an Ad Is Successfully Requested

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

HTTP/2 200
{
    "ads": [    ],
    "banners": [
       {
            "id": "string",
            "slotId": "string",
            "imageUrl": "string",
            "linkUrl": "string",
            "altText": "string",
            "expiry": "string"
        }
        {
            "id": "string",
            "slotId": "string",
            "imageUrl": "string",
            "linkUrl": "string",
            "altText": "string",
            "expiry": "string"
        }
        {
            "id": "string",
            "slotId": "string",
            "imageUrl": "string",
            "linkUrl": "string",
            "altText": "string",
            "expiry": "string"
        }
    ]
}

A mock version can be seen below:

HTTP/2 200
{
    "ads": [   ],
    "banners": [
        {
            "id": "postcheckout_GPZmwLMUH9n0_zfZTfn8UcmAShRlZmx",
            "slotId": "Post_Checkout",
            "imageUrl": "https://assets.example.com/q/mdNYanp7zYVG6h4zYlSduXfadhNUctYG_9gsNlPHQ9t=",
            "linkUrl": "https://www.externalsite.com/landingpage-campaign652936600",
            "altText": "An image of XYZ subscription service with a limited offer and a Shop Now button.",
            "expiry": "2002-10-02T15:00:00.05Z"
        }
        {
            "id": "postcheckout_GPZmwLMUH9n0_zfZTfn8Uct4ttrvx",
            "slotId": "Post_Checkout",
            "imageUrl": "https://assets.example.com/q/mdNYanp7zYVG6h4zYlSduXfadhNUctYG_f534c7b64",
            "linkUrl": "https://www.externalsite2.com/landingpage-campaign652954746",
            "altText": "An image of XYZ cruise holiday service with a limited offer and a Shop Now button.",
            "expiry": "2002-10-02T15:00:00.05Z"
        }
        {
            "id": "postcheckout_GPZmwLMUH9n0_zfZTfnxvtrvt245x",
            "slotId": "Post_Checkout",
            "imageUrl": "https://assets.example.com/q/mdNYanp7zYVG6h4zYlSduXfadhNUc4tg43z5",
            "linkUrl": "https://www.externalsite3.com/landingpage-campaign652945667",
            "altText": "An image of XYZ music festival stating tickets are now available.",
            "expiry": "2002-10-02T15:00:00.05Z"
        }
    ]
}

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:

POST $BASE_URL/v1/ads/generate HTTP/1.1 
accept: application/json
content-type: application/json
Authorization: Basic your_api_key_here
{
    "catalogId": "string",
    "customerId": "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",
        }
    ],
    "maxNumberOfAds": "number",
    "contentStandardId": "string",
    "bannerSlotIds": ["string"],
    "sessionId": "String"
}

A mock version can be seen below:

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

POST $BASE_URL/v1/ads/generate HTTP/1.1 
accept: application/json
content-type: application/json
Authorization: Basic 4ww25f70-b52s-40de-8f29-07b139b5cdc8
{
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "customerId": "3g4e33rr45s3",
    "pageType": "PostCheckout",
    "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",
        }
    ],
    "maxNumberOfAds": 4,
    "contentStandardId": "contentStandardId1",
    "bannerSlotIds": ["Post_Checkout"],
    "sessionId": "23dn3923-323d (this is a generated id that you control which identifies a user’s session). Optional"
}

What Happens when an Ad Is Successfully Requested

When you successfully request an ad, you receive the following object. In this instance the retailer has enabled tag tracking. This allows third party advertisers to track their banner with their own tracking tags. You will see this in the tagUrl field.

HTTP/2 200
{
    "ads": [    ],
    "banners": [
       {
            "id": "string",
            "slotId": "string",
            "imageUrl": "string",
            "linkUrl": "string",
            "altText": "string",
            "expiry": "string"
            "tagUrl": "string"
        }
        {
            "id": "string",
            "slotId": "string",
            "imageUrl": "string",
            "linkUrl": "string",
            "altText": "string",
            "expiry": "string",
            "tagUrl": "string"
        }
        {
            "id": "string",
            "slotId": "string",
            "imageUrl": "string",
            "linkUrl": "string",
            "altText": "string",
            "expiry": "string",
            "tagUrl": "string"
        }
    ]
}

A mock version can be seen below:

HTTP/2 200
{
    "ads": [   ],
    "banners": [
        {
            "id": "postcheckout_GPZmwLMUH9n0_zfZTfn8UcmAShRlZmx",
            "slotId": "Post_Checkout",
            "imageUrl": "https://assets.example.com/q/mdNYanp7zYVG6h4zYlSduXfadhNUctYG_9gsNlPHQ9t=",
            "linkUrl": "https://www.externalsite.com/landingpage-campaign652936600",
            "altText": "An image of XYZ subscription service with a limited offer and a Shop Now button.",
            "expiry": "2002-10-02T15:00:00.05Z"
            "tagUrl": "www.adtrackingservice.com/tagid=743djnfh78n4gc8i"
        }
        {
            "id": "postcheckout_GPZmwLMUH9n0_zfZTfn8Uct4ttrvx",
            "slotId": "Post_Checkout",
            "imageUrl": "https://assets.example.com/q/mdNYanp7zYVG6h4zYlSduXfadhNUctYG_f534c7b64",
            "linkUrl": "https://www.externalsite2.com/landingpage-campaign652954746",
            "altText": "An image of XYZ cruise holiday service with a limited offer and a Shop Now button.",
            "expiry": "2002-10-02T15:00:00.05Z"
            "tagUrl": "null"
        }
        {
            "id": "postcheckout_GPZmwLMUH9n0_zfZTfnxvtrvt245x",
            "slotId": "Post_Checkout",
            "imageUrl": "https://assets.example.com/q/mdNYanp7zYVG6h4zYlSduXfadhNUc4tg43z5",
            "linkUrl": "https://www.externalsite3.com/landingpage-campaign652945667",
            "altText": "An image of XYZ music festival stating tickets are now available.",
            "expiry": "2002-10-02T15:00:00.05Z"
            "tagUrl": "www.adtrackingservice.com/tagid=7fewf434f38i348d"
        }
    ]
}

As tagUrl is an optional field for third party advertisers, Project Agora Commerce may return a "null" result.

If your teamId is the same as the teamId for your catalog, the ?teamId=your_teamId_goes_here is optional and you may choose not to include it.

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

PreviousRequesting a Home Page Banner AdNextGraceful Fallback in the Event That No Ads Are Displayed

Last updated