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
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:
## 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:
HTTP Method: GET
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
## Getting a Bid Modifier
**HTTP Method: **GET
## 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:
|targeting_key||A targeting key, e.g. “country”||string||Required|
|comparator||How to interpret the value, this is usually “equals” but time* targeting keys allow “in_range” and segment can accept a “boolean_expression”||string||Required Valid choices are "equals", "in_range", and "boolean_expression".|
|value||The value to match, e.g. “USA”||Can be a string, boolean, or array. Numbers should be cast to strings.||Required|
|multiplier||Bid 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_override||When targeting List objects or 1st Party Segments, use the value in the List or Segment rather than this Term’s multiplier||boolean||Optional See details below.|
|recency||This 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.|
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
|Term ID||Targeting Key and Value||Multiplier|
|1||Browser = Safari||0.66|
|2||Browser = Chrome||2.0|
**Bid Price Calculation Examples**
|Auction Features||Matching Terms||Multipliers Applied||Final Bid Calculation|
|Browser = Safari Country = CAN||1||0.66||$3.00 * 0.66 = $1.98|
|Browser = Chrome Country = USA||2||2.0||$3.00 * 2.0 = $6.00|
|Browser = Safari Country = USA||1 and 2||0.66 and 2.0||$3.00 _ 0.66 _ 2.0 = $3.96|
|Browser = Chrome Country = CAN||none||none||$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**
**Domain List B**
|Term ID||Targeting Key and Value||Multipler||Dynamic Override|
|1||Domain List = A||1.0||True|
|2||Domain List = A||2.0||False|
|3||Country = CAN||0.66|||
**Bid Price Calculations**
|Column Title||Column Title||Column Title||Column Title|
|Domain = theonion.com Country = USA||1||0.75||$3.00 * 0.75 = $2.25|
|Browser = nbc.com Country = USA||1||4.0||$3.00 * 4.0 = $12.00|
|Browser = nytimes.com Country = CAN||2 and 3||2.0 and 0.66||$3.00 _ 2.0 _ 0.66 = $3.96|
|Browser = nbc.com Country = CAN||1 and 3||4.0 and 0.66||$3.00 _ 4.0 _ 0.66 = $7.92|
**Targeting keys that support dynamic overrides:**
App Bundle List
App ID 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.
|start||Min: 0 Max: 129600||int||Optional*. 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.|
|end||Min: 0 Max: 129600||int||Optional*. 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
|DELETE||A Bid Modifier cannot be deleted if it is attached to a Line Item or Campaign.|