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

Bid Modifier and Delivery Modifier Terms

❗️

Upgrade Notice

The Bid Modifier and Delivery Modifier APIs have been upgraded and all customers should use the new 2.0 APIs described here.

Like Targeting Modules, Buzz allows you to create lists of criteria for Bid Modifiers and Delivery Modifiers according to various targeting modules and keys. For example, you can indicate that when the browser is Safari the bid should be multiplied by 1.5.

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. Note that these keys do not fully match the List of Targeting Modules and Keys as some keys are only available for Modifiers and Models while others are only available for targeting.

A JSON object of Terms is an element of a POST or PUT to the bid_modifier endpoint or the delivery_modifier endpoint.

Modifier Terms JSON

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

FieldDescriptionNotes
targeting_moduleThe targeting module, e.g. geo
targeting_keyThe targeting key within the module, e.g. country
modifier_typeThe matching method for the modifier, default is INCLUDESee explanation below
valueThe value to match, e.g. USAMust always be a string, even if value is an integer or array
modifierAmount to apply to the modifier. For Bid Modifiers this will be the multiplier, for Delivery Models this will be the relative weight of delivery.Min=0 (don't bid)
Max = 10
field_labelHuman readable label for the field. Automatically added to the Terms.Cannot be set by the user.

An example of a Bid Modifier Term list is shown below:

[
  {
		"targeting_module": "geo",
		"targeting_key": "country",
		"value": "USA",
		"modifier": 0.8,
		"modifier_type": "include",
		"field_label": "USA"
  },
	{
		"targeting_module": "geo",
		"targeting_key": "country",
		"value": "CAN",
		"modifier": 2.3,
		"modifier_type": "include",
		"field_label": "CAN"
	},
	{
		"targeting_module": "platform",
		"targeting_key": "browser",
		"value": "Safari",
		"modifier": 1.3,
		"modifier_type": "include",
		"field_label": "Safari Browser"
	}
]

Modifier Types

There are four modifier_types associated with any Modifier Term. These types determine how the modifier is matched with a bid request. Note, although exclude is available as a targeting criteria, it is not allowed for modification since it would never match.

Modifier TypeMatching LogicNotes
includeTargeting criteria much match the value field exactly.Default modifier type
include_rangeTargeting criteria must be within range of values, for example a start and end timeOnly available on time and ip_address targeting modules.
booleanThe value field is passed as a string in a boolean expressionOnly available for segment targeting
dynamicThe multiplier provided in the Modifier Term is a default, the actual modifier is provided by the association of the user and the segment or the custom list item.Available for segment targeting as well as all Custom Lists types.

Row Limits

Delivery Modifiers are limited to 100 rows of terms. Bid Modifiers are limited to 1,000 rows.