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:

Field

Description

Type

Notes

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.

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 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

ID

List Item

Value

8

theonion.com

0.75

9

nbc.com

4.0

Domain List B

ID

List Item

Value

10

nytimes.com

1.25

11

cbs.com

3.5

Bid Modifier

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

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
  • 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
          },

Attribute

Values

Type

Description

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

Method

Restriction

GET

None

POST

None

PUT

None

DELETE

A Bid Modifier cannot be deleted if it is attached to a Line Item or Campaign.