Guides
Start typing to search…

Ad serving and tracking

With the Decision API, you can request/receive selected item lists. The properties in a request (items, search_query, and more) inside the inventory object may vary depending on the ad serving scenarios.

DecideAdProducts API (Sponsored Products)

The DecideAdProducts API for Sponsored Products enables serving ads from multiple inventories in a single request and supports deduplication of ad items across inventories. The API supports up to 5 inventory IDs per decision request, enabling bulk processing of multiple inventories.

Call the DecideAdProducts API for Sponsored Product Ads.

  • inventory_id: A unique identifier for the platform's inventory. This will be used to calculate metrics per inventory. An inventory represents a place (a mobile screen, a web page, etc.) where your ads will be displayed. Each inventory object within the request must be explicitly associated with an inventory_id.
  • num_ads: The number of ads you want to receive as an auction result.
📘

A maximum of 200 items may be requested across all inventories.

  • inventory_items: Required for PDP inventories. Each individual item_ID should be included in the request.
  • search_query: Required for search result inventories. The search query string should be included in the request.
  • inventories: An array of inventories to serve ads to in one request. When multiple inventories are included in a single request, retrieval strategies such as decision filtering can be applied per inventory.
  • deduplication_setting: Enables or disables deduplication across inventories. When enabled only items which are unique across all inventories are returned in the response. Deduplication occurs after each auction per inventory, guaranteeing unique ad items. When deduplication is requested via the API, the decision response will remove the item duplicates from the inventory_id based on the order in the request payload.

DecideAdBrands API (Sponsored Brands)

Call the DecideAdBrands API on the inventories you want to serve Sponsored Brands Ads.

  • inventory_id: A unique identifier for the platform's inventory. This will be used to calculate metrics per inventory.
  • num_ads: The number of ads you want to receive as an auction result.
  • items: Required for PDP inventories. The main item IDs on the page. For example, a homepage inventory may have few items, but a product-detail-page inventory will have one time.
  • search_query: Required for search result inventories. The search query string should be included in the request.

DecideAdDisplay API (Sponsored Display)

You should call the DecideAdDisplay API on the inventories you want to serve Sponsored Display Ads.

  • inventory_id: A unique identifier for the platform's inventory. This will be used to calculate metrics per inventory.
  • num_ads: The number of ads you want to receive as an auction result.
  • items: Required for PDP inventories. The main item IDs on the page. For example, a homepage inventory may have few items, but a product-detail-page inventory will have one time.
  • search_query: Required for search result inventories. The search query string should be included in the request.
  • video: Required for video ads. The requested video format for the decision request. (ex. MP4_360p, MP4_720p, HLS)

DecideAdItems API (Legacy)

🚧

The DecideAdProducts for Sponsored Product is a replacement for DecideAdItems, we highly recommend using the DecideAdProducts API as it provides enhanced features and bulk operations which are not supported in DecideAdItems. Please see v1.1 if you require further information on DecideAdItems.

DecideAdCreatives API (Legacy)

🚧

The DecideAdCreatives API is used for Sponsored Banner ads which is a legacy API. We recommend using Sponsored Brands or Sponsored Display APIs as a replacement for Sponsored Banner. Please see v1.0 if you require further information on the use of DecideAdCreatives.

Configuration

Detailed values for each property should be pre-arranged with your Moloco representative. To access the API, an API key and platform_id are required. API keys are created and managed through the Stand Alone Campaign Manger portal under Credential Management. Please see the Decision API reference and the MCM Decision API Client Library for JavaScript Github repository for more details and examples.

To enable API integration tests, Moloco provides two platform identifiers: one for testing and one for production usage. Using the testing Platform ID, you may send test requests and receive test responses filled with items selected from your catalog. Your MCM representative will provide you with the platform IDs during your initial onboarding.

🚧

You must integrate your catalog feed containing your item product data before using the Decision API

Response example for DecideAdProducts API

Sample DecideAdProducts response:

DecideAdProducts Response
{
"request_id": "product_request",
"decisions": [
  {
    "inventory_id": "home",
    "decided_items": [
      {
        "item_id": "item1",
        "auction_result": {
          "ad_account_id": "ad_account_1",
          "campaign_id": "campaign_1",
          "win_price": {
            "currency": "USD",
            "amount_micro": "130000000"
          }
        },
        "imp_trackers": [
          "https://eventsvc.com/t/i/MOLOCO?source=val1"
        ],
        "click_trackers": [
          "https://eventsvc.com/t/c/MOLOCO?source=val1"
        ],
        "track_id": "val1"
      }
    ]
  },
  {
    "inventory_id": "category",
    "decided_items": [
      {
        "item_id": "item2",
        "auction_result": {
          "ad_account_id": "ad_account_2",
          "campaign_id": "campaign_2",
          "win_price": {
            "currency": "USD",
            "amount_micro": "140000000"
          }
        },
        "imp_trackers": [
          "https://eventsvc.com/t/i/MOLOCO?source=val2"
        ],
        "click_trackers": [
          "https://eventsvc.com/t/c/MOLOCO?source=val2"
        ],
        "track_id": "val2"
      }
    ]
  },
  {
    "inventory_id": "search",
    "decided_items": [
      {
        "item_id": "item3",
        "auction_result": {
          "ad_account_id": "ad_account_3",
          "campaign_id": "campaign_3",
          "win_price": {
            "currency": "USD",
            "amount_micro": "110000000"
          }
        },
        "imp_trackers": [
          "https://eventsvc.com/t/i/MOLOCO?source=val3"
        ],
        "click_trackers": [
          "https://eventsvc.com/t/c/MOLOCO?source=val3"
        ],
        "track_id": "val3"
      },
      {
        "item_id": "item4",
        "auction_result": {
          "ad_account_id": "ad_account_4",
          "campaign_id": "campaign_4",
          "win_price": {
            "currency": "USD",
            "amount_micro": "160000000"
          }
        },
        "imp_trackers": [
          "https://eventsvc.com/t/i/MOLOCO?source=val4"
        ],
        "click_trackers": [
          "https://eventsvc.com/t/c/MOLOCO?source=val4"
        ],
        "track_id": "val4"
      }
    ]
  },
  {
    "inventory_id": "related_products",
    "decided_items": [
      {
        "item_id": "item5",
        "auction_result": {
          "ad_account_id": "ad_account_5",
          "campaign_id": "campaign_5",
          "win_price": {
            "currency": "USD",
            "amount_micro": "90000000"
          }
        },
        "imp_trackers": [
          "https://eventsvc.com/t/i/MOLOCO?source=val5"
        ],
        "click_trackers": [
          "https://eventsvc.com/t/c/MOLOCO?source=val5"
        ],
        "track_id": "val5"
      },
      {
        "item_id": "item6",
        "auction_result": {
          "ad_account_id": "ad_account_6",
          "campaign_id": "campaign_6",
          "win_price": {
            "currency": "USD",
            "amount_micro": "120000000"
          }
        },
        "imp_trackers": [
          "https://eventsvc.com/t/i/MOLOCO?source=val6"
        ],
        "click_trackers": [
          "https://eventsvc.com/t/c/MOLOCO?source=val6"
        ],
        "track_id": "val6"
      }
    ]
  },
  {
    "inventory_id": "custom_products",
    "decided_items": [
      {
        "item_id": "item7",
        "auction_result": {
          "ad_account_id": "ad_account_7",
          "campaign_id": "campaign_7",
          "win_price": {
            "currency": "USD",
            "amount_micro": "190000000"
          }
        },
        "imp_trackers": [
          "https://eventsvc.com/t/i/MOLOCO?source=val7"
        ],
        "click_trackers": [
          "https://eventsvc.com/t/c/MOLOCO?source=val7"
        ],
        "track_id": "val7"
      }
    ]
  }...

Response example for DecideAdBrands API

Sample DecideAdBrands response:

DecideAdBrands Response
{  
"request_id": "brand_request",  
"decisions": [  
  {  
    "inventory_id": "INVENTORY_ID",  
    "ads": [  
      {  
        "auction_result": {  
          "ad_account_id": "AD_ACCOUNT_ID",  
          "campaign_id": "CAMPAIGN_ID",  
          "win_price": {  
            "currency": "USD",  
            "amount_micro": "2100000"  
          }  
        },  
        "asset": {  
          "id": "ASSET_ID",  
          "banner": {  
            "image_url": "ASSET_IMAGE_URL"  
          },  
          "logo": {  
            "image_url": "LOGO_IMAGE_URL"  
          },  
          "headline": {  
            "text": "HEADLINE_TEXT"  
          },  
          "cta": {  
            "text": "CTA_TEXT"  
          },  
          "imp_trackers": [  
            "ASSET_IMP_TRACKER_URL"  
          ],  
          "click_trackers": [  
            "ASSET_CLICK_TRACKER_URL"  
          ]  
        },  
        "landing_page": {  
          "type": "CUSTOM_URL",  
          "custom_url_setting": {  
            "url": "<https://moloco.com">  
          }  
        },  
        "items": \[  
          {  
            "item_id": "1",  
            "imp_trackers": [  
              "ITEM_1_IMP_TRACKER_URL"  
            ],  
            "click_trackers": [  
              "ITEM_1_CLICK_TRACKER_URL"  
            ]  
          },  
          {  
            "item_id": "1044",  
            "imp_trackers": [  
              "ITEM_2_IMP_TRACKER_URL"  
            ],  
            "click_trackers": [  
              "ITEM_2_CLICK_TRACKER_URL"  
            ]  
            {
            ...

Response example DecideAdDisplay API

DecideAdDisplay Response
{  
"request_id": "display_request",  
"decisions": [  
  {  
    "inventory_id": "INVENTORY_ID",  
    "ads": [  
      {  
        "auction_result": {  
          "ad_account_id": "AD_ACCOUNT_ID",  
          "campaign_id": "CAMPAIGN_ID",  
          "win_price": {  
            "currency": "USD",  
            "amount_micro": "2100000"  
          }  
        },  
        "asset": {  
          "id": "ASSET_ID",  
          "banner": {  
            "image_url": "ASSET_IMAGE_URL"  
          },  
          "logo": {  
            "image_url": "LOGO_IMAGE_URL"  
          },  
          "headline": {  
            "text": "HEADLINE_TEXT"  
          },  
          "cta": {  
            "text": "CTA_TEXT"  
          },  
          "imp_trackers": [  
            "ASSET_IMP_TRACKER_URL"  
          ],  
          "click_trackers": [  
            "ASSET_CLICK_TRACKER_URL"  
          ]  
        },  
        "landing_page": {  
          "type": "CUSTOM_URL",  
          "custom_url_setting": {  
            "url": "<https://moloco.com">  
          }  
        },  
        "items": \[  
          {  
            "item_id": "1",  
            "imp_trackers": [  
              "ITEM_1_IMP_TRACKER_URL"  
            ],  
            "click_trackers": [  
              "ITEM_1_CLICK_TRACKER_URL"  
            ]  
          },  
          {  
            "item_id": "1044",  
            "imp_trackers": [  
              "ITEM_2_IMP_TRACKER_URL"  
            ],  
            "click_trackers": [  
              "ITEM_2_CLICK_TRACKER_URL"  
            ]  
            {
            ...

Calling tracker URLs

For more information please see the Calling trackers guide.

Updated about 1 month ago