Bid Modifiers

📘

Changes from v0.5 to v2.0

• Segment Recency definitions are now supported
• API has been simplified
• Must be using Targeting v2.0+ to enable

Overview

Bid Modifiers are objects that adjust bid prices up or down in real time based on the rules you set. For example, you might want to bid 50% more on a particular Domain List or 20% less during some hours of the day.

A single Bid Modifier can be associated with one or more Line Items or Campaigns. Campaign level Bid Modifiers will apply to any Line Items owned by the Campaign that do not themselves have Bid Modifiers associated.

Bid Modifiers work by multiplying bid prices up or down, depending on the rules you set. These rules are expressed as “Terms”, which define some inventory and a multiplier to adjust the bid with. In addition to defining Terms, you can also associate a Bid Model with a Bid Modifier. If an auction matches multiple Terms and/or a Bid Model row, all of the relevant multipliers will be applied.

📘

Full API documentation can be found here:

https://docs.beeswax.com/v2.0/reference/bid-modifiers-1

Supported Targeting Keys

Bid Modifier Terms use targeting keys to define swaths of inventory. The list of supported targeting keys can be found in the publicly accessible Microsoft Excel file on Github Bid and Delivery Model Fields or through the paginated reference API:

Reference API

• HTTP Method: GET
• URL: https://<--your-buzz-key-->.api.beeswax.com/rest/v2/ref/bid-modifier-targeting-keys

Note that these keys are not exactly the same as those in the List of Targeting Modules and Keys. Some targeting keys are only available for Bid or Delivery Modifiers, Bid or Delivery Models, or Targeting.

Creating a Bid Modifier

In order to create or modify Bid Modifiers with the Buzz API, you will need to use the bid-modifiers endpoint. This example shows the creation of a new Bid Modifier , you can use a GET request to access it later. Fields will be discussed in more detail below.

Full API Documentation can be found here.

HTTP Method: POST
URL: https://<--your-buzz-key-->.api.beeswax.com/rest/v2/bid-modifiers

{
   "bid_model_id":null,
   "name":"Bid Modifier Test",
   "alternative_id":"a-key-you-set",
   "account_id":1,
   "advertiser_id":null,
   "notes":"You can add up to 255 characters of human readable notes here",
   "active":true,
   "terms":[
      {
         "targeting_key":"country",
         "comparator":"equals",
         "value":"USA",
         "multiplier":1.25,
         "override_multiplier":false
      },
      {
         "targeting_key":"browser",
         "comparator":"equals",
         "value":"Safari",
         "multiplier":0.75,
         "override_multiplier":false
      }
   ]
}

Getting a Bid Modifier

HTTP Method: GET

URL: https://<--your-buzz-key-->.api.beeswax.com/rest/v2/bid-modifiers/<--bid_modifier_id-->

How Bid Modifier Terms are Expressed

Bid Modifier Terms are expressed as a list of JSON objects. Each Term object may contain the following fields:

Multipliers

The multiplier you set on a Bid Modifier Term will be applied to auctions that match the Term’s targeting criteria. If an auction matches multiple Terms, each multiplier will be applied. Example:

Bidding Strategy: Flat CPM with Pacing
CPM: $3.00

Bid Modifier

Bid Price Calculation Examples

Dynamic Overrides

When a Term targets a List object or a 1st party Segment it is possible to use the object’s value field to override the Term’s multiplier. For example, if you create a Domain List and assign each domain in the list a value, the override_multiplier toggle will cause those values to be used in place of the Term’s multiplier. Example:

Bidding Strategy: Flat CPM with Pacing
CPM: $3.00

Domain List A

Domain List B

Bid Modifier

Bid Price Calculations

Targeting keys that support dynamic overrides:

• App Bundle List
• App ID List
• Deal List
• Domain List
• IP Address List
• Placement ID List
• Publisher ID List
• Site ID List
• Lat. & Long. List
• Zip Code List
• 1st party Segments

Segment Recency

Segment Recency is a feature that lets you set bid multipliers based on when users were added to a given segment. For example, suppose people who visit your brand’s site are put into a segment called “Auto Intenders” and you want to bid more for people who have visited in the last 48 hours. Segment Recency enables you to bid more or less depending on how long ago users were added to a segment.

In order to use Segment Recency, you can simply use the segment targeting key, define the segment like normal, and then add the recency object, as shown below.

"terms": [
  		{
			"targeting_key": "segment",
			"comparator": "equals",
			"value": "buzz-123",
			"multiplier": 1.25,
			"recency": {“start”: 40, “end”: 120},
			"override_multiplier": false
		  },

• When defining a recency object, you must include either start or end, but you do not need to set both.

Term Limits

Bid Modifiers are limited to 1,000 Terms.

API Restrictions