"docs.beeswax.com" has a new address: "api-docs.freewheel.tv/beeswax." Please update your bookmarks accordingly.

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:

FieldDescriptionTypeNotes
targeting_keyA targeting key, e.g. “country”stringRequired
comparatorHow to interpret the value, this is usually “equals” but time* targeting keys allow “in_range” and segment can accept a “boolean_expression”stringRequired

Valid choices are "equals", "in_range", and "boolean_expression".
valueThe value to match, e.g. “USA”Can be a string, boolean, or array. Numbers should be cast to strings.Required
multiplierBid prices will be multiplied by this value to get a final bid price.Double cast to a string, e.g., “2.75”Required

Min: 0.0
Max: 100.0
multiplier_overrideWhen targeting List objects or 1st Party Segments, use the value in the List or Segment rather than this Term’s multiplierbooleanOptional

See details below.
recencyThis object describes the Segment Recency window and is described in more detail below.Object, see details below.Only include this attribute when using the Segment Recency feature.

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

Term IDTargeting Key and ValueMultiplier
1Browser = Safari0.66
2Browser = Chrome2.0

Bid Price Calculation Examples

Auction FeaturesMatching TermsMultipliers AppliedFinal Bid Calculation
Browser = Safari
Country = CAN
10.66$3.00 * 0.66 = $1.98
Browser = Chrome
Country = USA
22.0$3.00 * 2.0 = $6.00
Browser = Safari
Country = USA
1 and 20.66 and 2.0$3.00 0.66 2.0 = $3.96
Browser = Chrome
Country = CAN
nonenone$3.00

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

IDList ItemValue
8theonion.com0.75
9nbc.com4.0

Domain List B

IDList ItemValue
10nytimes.com1.25
11cbs.com3.5

Bid Modifier

Term IDTargeting Key and ValueMultiplerDynamic Override
1Domain List = A1.0True
2Domain List = A2.0False
3Country = CAN0.66

Bid Price Calculations

Domain = theonion.com
Country = USA
10.75$3.00 * 0.75 = $2.25
Browser = nbc.com
Country = USA
14.0$3.00 * 4.0 = $12.00
Browser = nytimes.com
Country = CAN
2 and 32.0 and 0.66$3.00 2.0 0.66 = $3.96
Browser = nbc.com
Country = CAN
1 and 34.0 and 0.66$3.00 4.0 0.66 = $7.92

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
		  },
AttributeValuesTypeDescription
startMin: 0
Max: 129600
intOptional*.

This is the start time of the recency window definition, as measured in minutes. A value of 60 means that the user must have been added to the segment more than 60 minutes ago. A value of 0 means that the user may have been added at any time up until the time of auction.
endMin: 0
Max: 129600
intOptional*.

This is the end of the lookback window, measured in minutes. A value of 120 means that the user must have been added to the segment within the last 120 minutes.
  • 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

MethodRestriction
GETNone
POSTNone
PUTNone
DELETEA Bid Modifier cannot be deleted if it is attached to a Line Item or Campaign.