Delivery Modifiers

📘

Changes from v0.5 to v2.0

• Targeting key combinations are now supported
• Budget caps are now supported
• API has been simplified
• Must be using Targeting v2.0+ to enable

Overview

Delivery Modifiers are objects that allocate spend to specific swaths of inventory in real time based on the rules you set. For example, you might use a Delivery Modifier to spend 50% of your budget on a particular Domain List, 25% on a specific Publisher, and 25% on any other inventory that doesn’t fall into the first two categories.

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

Delivery Modifiers work in tandem with pacing, so Campaigns or Line Items must have some form of pacing enabled to use this feature. Delivery Modifiers work by setting budget and pacing goals for individual slices of inventory, depending on the rules you set. These rules are expressed as “Terms”, which define some inventory and a “Weight”. A Term’s Weight determines how much of the budget it should receive. Rather than defining Terms, you can also associate a Delivery Model with a Delivery Modifier.

📘

Full API documenation can be found here:

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

Supported Targeting Keys

Delivery 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/delivery-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 Delivery Modifier

In order to create or modify Delivery Modifiers with the Buzz API, you will need to use the delivery-modifiers[link] endpoint. The following examples show the creation of a new Delivery Modifier as well as how to access it later. Each field 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/delivery-modifiers

{
  "delivery_model_id": null,
    "name": "Delivery 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,
    "fallback_weight": 1,
    "fallback_budget_cap_percentage": null,
    "terms": [
        {
        "targeting": [
            {
                "key": "country",
                "value": "CAN",
                "comparator": "equals",
                "expand_list": false
            },
            {
                "key": "domain_list",
                "value": "1",
                "comparator": "equals",
                "expand_list": true
            }
      	],
      	"weight": 10,
      	"rank": 2
  	    },{
          "targeting": [
            {
                "key": "country",
                "value": USA,
                "comparator": "equals",
                "expand_list": false
            },
            {
                "key": "domain_list",
                "value": "1",
                "comparator": "equals",
                "expand_list": true
            }
      	],
      	"weight": 50,
      	"rank": "1",
      	"budget_cap_percentage": 100
  	}
  ]
}

Getting a Delivery Modifier

HTTP Method: GET

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

How Delivery Modifier Terms Are Expressed

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

Term Fields

The targeting list represents a collection of targeting objects, which are described by their fields.

Targeting Fields

📘

Note

• There is a limit of 3 targeting key/value pairs per Term.
• All Terms in a Delivery Modifier must use matching sets of targeting keys. For example, if one Term uses the country and domain targeting keys, another Term can’t use publisher_id and device_type.

Weight

The Weight you set on a Delivery Modifier Term will determine approximately how much budget is spent on auctions that match the Term’s targeting criteria. Delivery Modifier Terms are expressed using Weights rather than hard budget figures so that spend can be adjusted across terms fluidly.

The percent of the total budget that will be allocated to some Term, k, is given by:

• budgetPercent = termWeight / sum(allTermWeights)

The total amount of spend expected for a Term is found by multiplying the Term’s budget percent by the total Line Item or Campaign budget.

Note that Delivery Modifiers do not guarantee that budgets will be spent in proportion to these weights. Line Item or Campaign pacing will take priority over Delivery Modifier budget allocation if any of the Terms represent constrained inventory. For example, if a Delivery Modifier has Terms A and B, each with a weight of 10, but Term B’s inventory is rare, it is possible that a disproportionate amount of the budget will be spent on Term A in order to ensure smooth delivery pacing.

Weight Examples

The following examples assume a budget of $1500.

Example 1: Single Key Delivery Modifier
In this example the user wants 20% of their budget to be spent on traffic from the Safari browser with the remaining 80% spent on Chrome. They’ve defined a Delivery Modifier with two Terms using the browser targeting key. The Terms are set with Weights 1 and 4 in order to achieve the desired budget split.

• Note: In this example, the same result could be achieved using any other weights that maintain the 1:4 ratio. Weight ratios of 1:4, 5:20, and 10:40 are functionally equivalent.

Single Key Delivery Modifier

Example 2: Multi-Key Delivery Modifier
Following the first example above, the user wants to further specify their budget’s delivery by country in addition to browser. Here they want to maintain the 1:4 ratio for browser delivery while also establishing a 1:3 split on spend between Canada and the US. In order to do this a second targeting key is introduced and each combination is given a weight in proportion to the desired outcome.

A Delivery Modifier can have up to 3 different targeting keys. If you require more than 3 targeting keys to shape your spend, consider using a Delivery Model instead.

Multi-Key Delivery Modifier

Ranks

The Rank field is used to break ties when multiple Delivery Modifier Terms match a given impression. Consider Example 2 in the Weight Examples section directly above. If an impression matches Chrome but has no country then spend could be attributed to either Term B or Term C. Spend will be attributed to the highest ranking Term. If the highest ranking term is delivering on pace then the spend will be attributed to the second highest ranking term, and so on.

Ranks must be unique across Terms and set in sequential order starting from 1.

As a best practice, you should give higher ranks to slices of inventory that are most important to deliver against.

Expanded Lists

When a Delivery Modifier Term targets a List object it is possible to weight delivery across the List items according to their value fields. If you use a Domain List, the expand_list feature will spend on the various domains in proportion to their List values. This works by “expanding” the Items in the List to create a number of virtual Delivery Modifier Terms in the backend. See the Term Limits section for more details.

To see how Expanded Lists work, suppose a user has created two Domain Lists, A and B, as well as a Delivery Modifier with two Terms that target these Domain lists respectively. The user would like the budget allocated to Domain List A to be spent in proportion to the List’s values (i.e., in a 1:4 ratio), so they enable the Expand List feature for Term 1. The user has no requirement for how budget is spent across the domains in Domain List B, so they don’t enable Expand List for Term 2:

Domain List A

Domain List B

Delivery Modifier

Example Spend By Domain

Targeting keys that support expansion:

• App Bundle List
• App ID List
• Deal List
• Domain List
• Placement ID List
• Publisher ID List
• Site ID List
• Lat. & Long. List
• Zip Code List

Budget Caps

Budget Caps can be used to set hard limits on the amount that a single Term can spend. For example, if you want to spend 25% but not more than 50% of your budget on a particular domain, you could configure a Delivery Modifier with a Budget Cap. The value of a Budget Cap represents the maximum percent of budget that can be spent on a Term.

In order to avoid under delivery it is not possible to set a budget cap that is lower than the Term’s allocated budget percent based on weight. If a Term’s weighted budget percent is 20% then its Budget Cap must be greater than or equal to 20.

Example: Budget Cap Delivery Modifier

Term Limits

A Delivery Modifier can not contain more than 100 Terms. The additional backend Terms created by Expanded List items are counted against this limit. For example, see the following Domain List and Delivery Modifier. Expanding the Lists on two of these Terms causes additional Terms to be created in the backend representation.

Domain List A

Delivery Modifier (4 rows)

Expanded Backend Representation (6 rows)

Fallback Weight

Fallback Weight is set at the Delivery Modifier level but it functions similar to a Term’s Weight. The Fallback Weight feature enables you to allocate a portion of your budget to any inventory not otherwise targeted in the Delivery Modifier. This can be helpful for:

• Prospecting campaigns
• Exploring inventory for optimization
• Assuring total delivery when inventory is constrained

For example, suppose that you want to set a 1:3 budget split between Desktop and Mobile Phone inventory and that you also want to allocate 20% of your budget to inventory that doesn’t come from Desktop or Mobile devices. In order to achieve this, you can set a Fallback Weight like so:

Example: Fallback

If the Fallback Weight is set to 0 it means that nothing can be spent outside of the defined Delivery Modifier Terms. This can pose a risk of under delivery if inventory is constrained. Because of this, as a best practice we recommend setting a Fallback Weight greater than 0.

The Fallback Weight setting supports a Budget Cap. The Fallback Budget Cap functions the same way as Term Budget Caps and, like the Term Budget Caps, may pose a risk to under delivery.

API Restrictions