Guides

Ad Requests and Response Examples

Suggest Edits

Homepage - Sponsored Products and Banner Ads

Using Martailer Combined Ads you can request multiple ads and ad formats in a single call. In this case, for the homepage, we will request 3 banners and 5 sponsored product ads!


Ad Request

📘

You can find the banner slot id when creating banner slots on the admin panel

curl --request POST \
     --url https://api.martailer.com/v1/combined/ads \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'x-api-key: YOUR API KEY SANDBOX/PROD' \
     --data '
{
  "placement": "home",
  "storeId": "YOUR STORE ID SANDBOX/PROD",
  "visitorId": "VISITOR ID",
  "customerId": "CUSTOMER ID",
  "numberOfSPAds": 5,
  "bannerSlots": [
    {
      "numberOfAds": 3,
      "slotId": "HOME PAGE BANNER SLOT ID"
    }
  ],
  "language": "SE"
}
'

Response

Please see the example of response for the request above. Link URL comes from the campaign process

{
  "storeId": "f3be0a05-2e17-47ba-b4c4-8d2e28d475b8",
  "sponsoredProducts": [
    {
      "itemId": "34af2g564",
      "adId": "ad_f879f5be4c74bdf9211440a4361ae355",
      "position": 1
    },
    {
      "itemId": "9943tjdfgs",
      "adId": "ad_6caed8c3cc69605068b1238c1fd3165b",
      "position": 2
    },
    {
      "itemId": "093458aadf",
      "adId": "ad_8odfgaed8c3cc69605068b1238cjkn89u",
      "position": 3
    },
    {
      "itemId": "js099458",
      "adId": "ad_asdcaed8c3cc69605068b12a1fd31sfsd",
      "position": 4
    },
    {
      "itemId": "7693lk697",
      "adId": "ad_6caed8c3cc69605068b1238c1fd3dskjg",
      "position": 5
    }
  ],
  "banners": [
    {
      "adId": "3f7de72f-be77-4bbd-a113-e88ac9b4add0",
      "imageUrl": "https://d3b73qinmxbt5w.cloudfront.net/b/-aa4118da-6c6e-4a70-9fde-ASWQDCV=",
      "linkUrl": "https://www.example.com/link",
      "altText": "",
      "slotId": "HOME PAGE BANNER SLOT ID",
      "position": 1
    },
    {
      "adId": "3f7de72f-be77-4bbd-a113-e88ac9b46gfhj",
      "imageUrl": "https://d3b73qinmxbt5w.cloudfront.net/b/-bba5118da-6c6e-4a70-9fde-ASWQDCV:",
      "linkUrl": "https://www.example.com/link2",
      "altText": "",
      "slotId": "HOME PAGE BANNER SLOT ID",
      "position": 2
    },
    {
      "adId": "3f7de72f-be77-4bbd-a113-e88ac9b46gfhj",
      "imageUrl": "https://d3b73qinmxbt5w.cloudfront.net/b/-bba5118da-6c6e-4a70-9fde-ASWQDCV:",
      "linkUrl": "https://www.example.com/link2",
      "altText": "",
      "slotId": "HOME PAGE BANNER SLOT ID",
      "position": 3
    }
   ]
}


Category Pages

  • 1-3 banners on top of the page
  • 2 sponsored product ads on top of the grid
  • 1-3 banners at the bottom of the page

Ad Request

curl --request POST \
     --url https://api.martailer.com/v1/combined/ads \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'x-api-key: YOUR API KEY SANDBOX/PROD' \
     --data '
{
  "placement": "category",
  "storeId": "YOUR STORE ID SANDBOX/PROD",
  "visitorId": "VISITOR ID",
  "customerId": "CUSTOMER ID",
  "numberOfSPAds": 2,
  "bannerSlots": [
    {
      "numberOfAds": 3,
      "slotId": "CATEGORY TOP PAGE BANNER SLOT ID"
    },
    {
      "numberOfAds": 3,
      "slotId": "CATEGORY BOTTOM PAGE BANNER SLOT ID"
    }
  ],
  "category": "parfume_23_98lladf",
  "language": "SE"
}
'

Response

Please see the example of response for the request above. Link URL comes from the campaign process

{
  "storeId": "f3be0a05-2e17-47ba-b4c4-8d2e28d475b8",
  "sponsoredProducts": [
    {
      "itemId": "34af2g564",
      "adId": "ad_f879f5be4c74bdf9211440a4361ae355",
      "position": 1
    },
    {
      "itemId": "9943tjdfgs",
      "adId": "ad_6caed8c3cc69605068b1238c1fd3165b",
      "position": 2
    }
  ],
  "banners": [
    {
      "adId": "3f7de72f-be77-4bbd-a113-e88ac9b4add0",
      "imageUrl": "https://d3b73qinmxbt5w.cloudfront.net/b/-aa4118da-6c6e-4a70-9fde-ASWQDCV=",
      "linkUrl": "https://www.example.com/link",
      "altText": "",
      "slotId": "CATEGORY TOP PAGE BANNER SLOT ID",
      "position": 1
    },
    {
      "adId": "3f7de72f-be77-4bbd-a113-e88ac9b46gfhj",
      "imageUrl": "https://d3b73qinmxbt5w.cloudfront.net/b/-bba5118da-6c6e-4a70-9fde-ASWQDCV:",
      "linkUrl": "https://www.example.com/link2",
      "altText": "",
      "slotId": "CATEGORY TOP PAGE BANNER SLOT ID",
      "position": 2
    },
    {
      "adId": "3f7de72f-be77-4bbd-a113-e88ac9b46gfhj",
      "imageUrl": "https://d3b73qinmxbt5w.cloudfront.net/b/-bba5118da-6c6e-4a70-9fde-ASWQDCV:",
      "linkUrl": "https://www.example.com/link2",
      "altText": "",
      "slotId": "CATEGORY TOP PAGE BANNER SLOT ID",
      "position": 3
    },
    {
      "adId": "98f098d8-be77-4bbd-a113-e88ac9b4add0",
      "imageUrl": "https://d3b73qinmxbt5w.cloudfront.net/b/-aa4118da-6c6e-4a70-9fde-ASWQDCV=",
      "linkUrl": "https://www.example.com/link",
      "altText": "",
      "slotId": "CATEGORY BOTTOM PAGE BANNER SLOT ID",
      "position": 1
    },
    {
      "adId": "98890098gs-be77-4bbd-a113-e88ac9b46gfhj",
      "imageUrl": "https://d3b73qinmxbt5w.cloudfront.net/b/-bba5118da-6c6e-4a70-9fde-ASWQDCV:",
      "linkUrl": "https://www.example.com/link2",
      "altText": "",
      "slotId": "CATEGORY BOTTOM PAGE BANNER SLOT ID",
      "position": 2
    },
    {
      "adId": "346lkd980-be77-4bbd-a113-e88ac9b46gfhj",
      "imageUrl": "https://d3b73qinmxbt5w.cloudfront.net/b/-bba5118da-6c6e-4a70-9fde-ASWQDCV:",
      "linkUrl": "https://www.example.com/link2",
      "altText": "",
      "slotId": "CATEGORY BOTTOM PAGE BANNER SLOT ID",
      "position": 3
    }
   ]
}

Search Results

  • 1-3 banner on top of the page
  • 2 sponsored products

Ad Request

curl --request POST \
     --url https://api.martailer.com/v1/combined/ads \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'x-api-key: YOUR API KEY SANDBOX/PROD' \
     --data '
{
  "placement": "search",
  "storeId": "YOUR STORE ID SANDBOX/PROD",
  "visitorId": "VISITOR ID",
  "cusotmerId": "CUSTOMER ID",
  "searchTerm": "damparfym",
  "numberOfSPAds": 2
  "bannerSlots": [
    {
      "numberOfAds": 3,
      "slotId": "SEARCH RESULTS PAGE BANNER SLOT ID"
    }
  ],
  "language": "SE"
}
'

Response

{
  "storeId": "f3be0a05-2e17-47ba-b4c4-8d2e28d475b8",
  "sponsoredProducts": [
    {
      "itemId": "34af2g564",
      "adId": "ad_f879f5be4c74bdf9211440a4361ae355",
      "position": 1
    },
    {
      "itemId": "9943tjdfgs",
      "adId": "ad_6caed8c3cc69605068b1238c1fd3165b",
      "position": 2
    }
  ],
  "banners": [
    {
      "adId": "3f7de72f-be77-4bbd-a113-e88ac9b4add0",
      "imageUrl": "https://d3b73qinmxbt5w.cloudfront.net/b/-aa4118da-6c6e-4a70-9fde-ASWQDCV=",
      "linkUrl": "https://www.lyko.com/link",
      "altText": "",
      "slotId": "SEARCH RESULTS PAGE BANNER SLOT ID",
      "position": 1
    },
    {
      "adId": "3f7de72f-be77-4bbd-a113-e88ac9b46gfhj",
      "imageUrl": "https://d3b73qinmxbt5w.cloudfront.net/b/-bba5118da-6c6e-4a70-9fde-ASWQDCV:",
      "linkUrl": "https://www.lyko.com/link2",
      "altText": "",
      "slotId": "SEARCH RESULTS PAGE BANNER SLOT ID",
      "position": 2
    },
    {
      "adId": "3f7de72f-be77-4bbd-a113-e88ac9b46gfhj",
      "imageUrl": "https://d3b73qinmxbt5w.cloudfront.net/b/-bba5118da-6c6e-4a70-9fde-ASWQDCV:",
      "linkUrl": "https://www.lyko.com/link2",
      "altText": "",
      "slotId": "SEARCH RESULTS PAGE BANNER SLOT ID",
      "position": 3
    }
   ]
}


PDP

  • 1 sponsored product on recommended products

Ad Request

curl --request POST \
     --url https://api.martailer.com/v1/combined/ads \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'x-api-key: YOUR API KEY SANDBOX/PROD' \
     --data '
{
  "placement": "product",
  "storeId": "YOUR STORE ID SANDBOX/PROD",
  "visitorId": "VISITOR ID",
  "cusotmerId": "CUSTOMER ID",
  "numberOfSPAds": 1,
  "itemId": "PRODUCT ID OF PDP"
}
'

Response

{
  "storeId": "f3be0a05-2e17-47ba-b4c4-8d2e28d475b8",
  "sponsoredProducts": [
    {
      "itemId": "34af2g564",
      "adId": "ad_f879f5be4c74bdf9211440a4361ae355",
      "position": 1
    }
  ]
}

Updated 2 months ago