Use the External Pricing API

This page describes how to compute pricing information by using a third-party integration.

External Pricing API

The external pricing API feature allows you to bypass the internal Guaranteed Campaigns rate cards and manage pricing externally through your own pricing engine. This way, the Guaranteed Campaigns module ingests pricing data from your external pricing engine, offering flexibility and control over the pricing strategy.

  • The external pricing API provides a CPM override to the line item.
  • The CPM override reflects the externally managed pricing and appears in the CPM Overwrite field on the Create a Digital Line Item.

Note: The CPM will only be updated if you modify anything on the line item, which ensures that pricing remains stable unless you make any edits.

You can set the URL and API key of your external pricing API endpoint in the Domain settings. See Pricing API.

Note: Guaranteed Campaigns settings are available only to users assigned the Admin or Direct Sales Admin role. For more information, see User Permissions.

To configure the external pricing API endpoint:

  1. Access the Settings page.
  2. In the Guaranteed tab, click Digital Inventory.

  3. In the Pricing API part, enter the URL for the external pricing endpoint and your API Authentication key.

To use the External Pricing API in the Guaranteed Campaigns module and perform final calculations for different types of buy, follow these steps:

To use the External Pricing API:

  1. Create a Guaranteed Campaign.
  2. Choose the screens and configure ad settings such as type of buy, ad length, and duration as usual.
  3. Provide one of the following pricing values based on the type of buy.
    • The Price for the following types of buy:
      • Frequency
      • Share of Voice
      • Takeover
    • The CPM for the following types of buy:
      • Impression
      • Budget
      • Plays

With the Price or CPM value, the Guaranteed Campaigns module can communicate with the External Pricing API. The API will fetch and update the pricing information dynamically based on the specified type of buy.

The Guaranteed Campaigns module performs the final calculation using the pricing information received from the External Pricing API.

The calculated values are then used to complete the setup of the line item, ensuring accurate and dynamic pricing for the specified type of buy.

The Guaranteed Campaigns module calculates the line item summary based on the values received by the pricing engine and displays them on the UI:

For:

  • Frequency
  • Share of Voice
  • Takeover

For:

  • Impressions
  • Budget
  • Plays

Note: If the Pricing API does not return a value, the Overwrite box is activated so that you can enter the desired price/CPM manually. See CPM Overwrite.

You can also override the cost of the line item. In this case, Guaranteed Campaigns will consider the override value for final price calculation.

The following describes how the External Pricing API works.

The Guaranteed Campaigns module sends all the selection details to the external pricing engine with the following API call:

Copy 
POST https://direct.broadsign.com/api/v1/third_party/pricing

The following is a sample payload:

Copy 
{
"schedule":
{
"start_date":"2023-12-19",
"end_date":"2024-01-01",
"start_time":"00:00:00",
"end_time":"23:59:59",
"dow_mask":127,
"slot_duration":15
},
"screens":[224016,224020],
"filters":[],
"buy_mode":
{
"type":"ppl",
"values":{"bs_saturation":1,"saturation":1,"custom_cpm":0},
"active":true
}
}

The following is a sample response for the following types of buy:

  • Frequency
  • Share of Voice
  • Takeover
Copy 
{
"override_type": "price",  #override type is price for these type of buys, Direct will expect a price value
"value": 450.0             #final value of price returned
}

The following is a sample response for the following types of buy:

  • Impression
  • Budget
  • Plays
Copy 
{
"value": 10.0,            #final value of CPM returned
"override_type": "cpm"    #override type is CPM for these type of buys, Direct will expect a CPM value
}

You can call the pricing engine to extract the recent values sent by the external pricing engine with the following API:

Copy 
GET /api/v1/third_party/pricing/logs/proposal_item/<proposal_item_id>

The following is a sample response to that call:

Copy 
   "id":12345,
   "override_type": "cpm",
   "value":10.0,
   "arbitrary_additional_info":
{
      "screens":[
         {
            "id":"1",
            "Cpm":15.0 // CPM for screen 1
         },
         {
            "id":"2",
            "Cpm": 2.0  // CPM for screen 2
         }
      ]

The Guaranteed Campaigns module will cache the response of any upstream API call made for a duration of 20 minutes.

You can clear your cache at any time by using the following endpoint:

Copy 
POST api/v1/pricing/cache_clear