Overview

Like delivery modifiers, delivery models create the ability to finely control the distribution of programmatic ads separately from the prices that will be bid for those ads. This unique capability dynamically shifts the budget according to a set of instructions defined during the creation of the model while ensuring full delivery. A delivery model can be uploaded and used in place of modifier terms that are input directly into the UI. The delivery model will contain a collection of delivery modifier terms.

Delivery models and modifiers allocate spending to specific inventory in real-time based on defined rules. For instance, a delivery model or modifier can be set to allocate 50% of the budget to a particular Domain List, 25% to a specific Publisher, and 25% to other inventory that meets targeting criteria. Delivery models and modifiers can be linked to one or more Line-Items or Campaigns. At the Campaign level, the delivery model or modifier applies to all associated Line-Items that do not have their own existing delivery model or modifier. Both delivery models and modifiers can be used with a custom bidding agent, but pacing must be enabled on the custom bidding strategy. If pacing is not available as an option, the account team can be contacted to have it set up.

How It Works

Delivery Model Example Distribution

A Delivery Model might consist of the following criteria:

Criteria	Value	Weight	Target Budget
O&O Deal ID List	10	50%	$5,000
Other Deal ID List	8	40%	$4,000
Open Exchange	2	10%	$1,000

This model dynamically reallocates the budget to meet the overall target, ensuring the ad spend is optimized based on available inventory. If inventory from higher-priority sources (e.g., O&O) is unavailable, the budget is reallocated to secondary sources (e.g., open exchange).

Budget Allocation and Pacing

Beeswax’s pacing system ensures that each term within the Delivery Model is paced according to the Line-Item’s pacing settings (Daily, Lifetime, or Flight). The system recalculates budget allocations and bid probabilities regularly to ensure full delivery of the total budget.

Pacing Rules: The pacing of each Term is based on the line item's pacing settings. If a Term under-delivers, its unspent budget is redistributed to other Terms within the Delivery Model to maintain delivery schedules.
Example of Delivery Model Reallocation: If the O&O inventory is insufficient to deliver the required impressions, the budget is automatically reallocated to other inventory sources (e.g., Other Deals or Open Exchange) based on their assigned weight.

Upload and Create Delivery Models

Delivery Models and Bid Models can be used on the same line item. A Delivery Model controls the delivery, while a Bid Model controls the bid price. However, Deliver Models and Modifiers can not be used on the same line item.

1. The first step is to create the model offline.

This can be done by training a model using Beeswax log data, or a different first/third party data source, or any other modeling technique. The delivery model consists of 2 files: the manifest file and the prediction file.

2. Creating the Prediction File:

Prediction files are the table that contains the delivery model. Prediction files should be kept to a maximum of 100 rows to optimize loading performance and should be in the below format:

pipe-delimited ("|") text files
no compression
first row of each file contains headers
at least one bid request key field
a required field called "value", which represents either the relative delivery weight for that row, from 0 to 1000
null values should be left blank
an asterisk (*) can optionally be used to match any value (note: a maximum of three wildcard fields are supported

3. Creating the Manifest File: The manifest file is a .json file with the below format. The model predictions object includes a list of S3 paths to all prediction files (previous step) associated with this model version. The files live under the following path: s3://beeswax-data-<region>/bid_models/<buzz key>/. The metadata.fields object contains a list of feature fields that are included in this model version and, optionally, the fields which contain wildcards.

When creating the Prediction File you should assure that each row is mutually exclusive in criteria. If multiple rows could be matched to a given auction, then delivery may not match your expectations.

How to Upload a Delivery Model:

If a model with more than 100 rows is uploaded, an error will appear on the manifest upload page, notifying that the delivery model file is too large. Additionally, only a single file upload is allowed for Delivery Models.

In order to use a delivery model, the files must be uploaded to S3. Please reach out to your support alias if you are not set up for this and request access. Instructions on how to access S3 buckets for upload can be found here.
Once access is granted, follow the API documentation to upload the manifest and data files to s3://beeswax-data-<region>/bid_models/<buzz key>/. Regardless of which region you upload the files to, the data will be replicated to each region in which your bidder is live.
File structure is largely flexible, but please note that manifest files must be under the following path: s3://beeswax-data-<region>/bid_models/<buzz key>/customer_manifests/.

How to Create a Delivery Model

The final step to creating and using delivery models is to create the delivery model in the UI. API instructions can be found here

Select Create > Model.

Enter the following fields in the Overview screen.
*Required

Field Name	Description
Model ID	An ID associated to the model generated after creation.
Model Name*	Desired name for the Model.
Value Type*	Select Budget Weight for a delivery model.
Alternative ID	Any number or string. Used to map this object to an object in an outside system.
Active	Active or Inactive.
Notes	Any desired notes about this model.

Click Save & Continue

From the Model Versions screen, create the first Delivery Model version by entering the Manifest S3 Path (location of the pre-loaded manifest file) and Model Version Name.
The model will automatically go into ‘PENDING’ status. This status signifies the version is being validated and prepared to receive traffic.
The final step is to associate the delivery model with a line item. Under the Modifiers tab during line item creation, an existing bid model may be selected.

The updated versions of the delivery model table can be uploaded to the same delivery model object in the UI, and the most recent upload version will be used unless otherwise specified.