Skip to end of metadata
Go to start of metadata

Insertion Order Service

Insertion orders enable you to better organize, track, and allocate budget to your line items. Additionally, budget intervals (i.e., sets of flight dates each with their own pacing and budget) can be used on insertion orders, allowing you to represent available budget in a way that more accurately reflects your contract with an advertiser. AppNexus suggests using insertion orders and budget intervals.

As a best practice, align currency to the billing currency in order to achieve the best possible local currency experience.

Insertion orders can be associated with one or more line items. A line item can belong to multiple insertion orders as long as the budget intervals on those insertion orders do not overlap.

Seamless insertion orders

There are two types of insertion orders: seamless and non-seamless (legacy). The main difference between seamless and non-seamless insertion orders in terms of setup are outlined below:

  • To create a seamless insertion order, you must: 
    • use the budget- and pacing-related fields and the start_date and end_date fields in the budget_intervals array to specify the dates during which the insertion order should run, what budget is available to it during those dates and how spending of the budget should be paced.
    • leave the start_date and end_date fields (and any budget or pacing related fields) on the main insertion order level set to null.
    • only associate seamless line items with seamless insertion orders. For instructions on how to create seamless line items, see Line Item Service.
  • To create a non-seamless insertion order, you must:
    • use the budget and pacing related fields and the start_date and end_date fields on the main insertion order object to specify the dates during which the insertion order should run, what budget is available to it during those dates and how the spending of the budget should be paced.
    • ensure the budget_intervals field is set to null.  

    • only associate non-seamless line items with non-seamless insertion orders. For instructions on how to create non-seamless line items, see Line Item Service.

Seamless insertion orders are the preferred model. You should use the seamless insertion order workflow when creating new insertion orders. You cannot convert a non-seamless insertion order to seamless or link non-seamless line items to seamless insertion orders.

In the UI version of Console, API budget_intervals are referred to as "Billing Periods".

On This Page

REST API

Add a new insertion order:
POST https://api.appnexus.com/insertion-order?advertiser_id=ADVERTISER_ID
(insertion order JSON)

Modify an existing insertion order:
PUT https://api.appnexus.com/insertion-order?id=INSERTIONORDER_ID&advertiser_id=ADVERTISER_ID
(insertion order JSON)

View all of the insertion orders for one of your advertisers:
GET https://api.appnexus.com/insertion-order?advertiser_id=ADVERTISER_ID

View a specific insertion order for one of your advertisers:  
GET https://api.appnexus.com/insertion-order?id=INSERTIONORDER_ID

View multiple insertion orders by ID using a comma-separated list:
GET https://api.appnexus.com/insertion-order?id=1,2,3

Search for insertion orders with IDs or names containing certain characters:
GET https://api.appnexus.com/insertion-order?search=SEARCH_TERM

Find out which fields you can filter and sort by:
GET https://api.appnexus.com/insertion-order/meta

JSON Fields

Field

Type

Description

Default

Required On

id

int

The ID of the insertion order.

N/A

PUT

name

string

The name of the insertion order. (Maximum of 255 characters.)

N/A

POST

code

string

The custom code for the insertion order. The code may only contain alphanumeric characters, periods, underscores or dashes. The code you enter is not case-sensitive (upper- and lower-case characters are treated the same). No 2 objects at the same level (e.g., line items or campaigns) can use the same code per advertiser. For example, 2 lines items cannot both use code "XYZ", but a single line item and its child campaign can.

Note that there may also be a custom code per budget interval. See the Budget Intervals array below for more details.

null

 

state

enum

The state of the insertion order. Possible values: "active" or "inactive".

"active"

 

advertiser_id

int

The ID of the advertiser.

N/A

POST

start_date

timestamp

The start date of the non-seamless insertion order. If you are creating a seamless insertion order, do not set this field.

null (immediately)

 

end_date

timestamp

The end date of the non-seamless insertion order. If you are creating a seamless insertion order, do not set this field.

null (indefinitely)

 

remaining_daysintRead-only.  The number of days between today and the  end_date  for the insertion order. Note: This will be null if the  start_date  is in the future or if either the  start_date  or  end_date  is not set.N/A 
total_daysintRead-only.  The number of days between the start_date  and  end_date  for the insertion order. Note: This will be null if either the start_date  or  end_date  is not set.N/A 

last_modified

timestamp

Read-only. The time of the last modification to this campaign.

N/A 

timezone

string

The timezone by which budget and spend are counted. For a list of acceptable timezone values, see API Timezones.

Any PUT calls to the advertiser service which include set_child_timezone=true in the query string will cause any timezone settings on the lower level objects (e.g., insertion orders, line items, campaigns) to be overridden with the latest timezone value for that advertiser.

"EST5EDT" or the advertiser's timezone

 

currency

string

The currency assigned to the insertion order. For a full list of available currencies, use the read-only Currency Service. Note: Once the insertion order has been created, the currency cannot be changed.

Default currency of the advertiser 

 

comments

string

Comments about the insertion order.

N/A

 

billing_codestringThe billing code for the insertion order. This will only appear on invoices that are insertion order-specific (e.g., if you receive an invoice per insertion order). For details on invoices, see Understanding Your Invoice (customer login required).null 

line_items

array of objects

The line items which are associated with the insertion order. For more information, see Line Items.

Seamless insertion orders may only be associated with seamless line items. Non-seamless insertions orders may only be associated with non-seamless line items.

N/A

 

labels

array of objects

The labels assigned to the insertion order. See Labels.

N/A

 

broker_fees

array of objects

The commissions that the network must pass to brokers when serving an ad. These commissions are deducted from the booked revenue (the amount the network receives from the advertiser) and are typically for brokering a relationship with the advertiser. They can either be a percentage of the revenue or a flat CPM. See Broker Fees below for more details.

Broker fees at the line item level override broker fees at the insertion order level.

N/A

 

budget_intervals array of objects
This array is only relevant to and required for seamless insertion orders (if the insertion order is non-seamless, leave this field set to null).

Budget intervals enable multiple date intervals to be attached to an insertion order, each with corresponding budget values. See Budget Intervals below for more details.

If you use budget_intervals, the following fields should not be used on the top level insertion order object:

  • lifetime_pacing
  • lifetime_budget
  • lifetime_budget_imps
  • enable_pacing
  • lifetime_pacing_span
  • allow_safety_pacing
  • daily_budget
  • daily_budget_imps
  • lifetime_pacing_pct
N/A 
budget_typeenum

The budget type of the insertion order. Values may be 'revenue' or 'impression'.

  • If this field is set to 'impression' then both the lifetime_budget and daily_budget fields must be set to null.
  • If this field is set to 'revenue' then both the lifetime_budget_imps and daily_budget_imps fields must be set to null.
  • This field must be set when all 4 budget fields in the budget_intervals array (lifetime_budgetlifetime_budget_impsdaily_budget and daily_budget_imps) have been set to null.
  

lifetime_pacing

boolean

If true, the non-seamless insertion order will attempt to spend its overall lifetime budget evenly over the insertion order flight dates. If true :

  • You must establish a lifetime_budget or lifetime_budget_imps
  • You must establish a start_date and end_date
  • You cannot set a daily_budget
  • You cannot set enable_pacing to false
Only applicable to non-seamless insertion orders.
null 
lifetime_budget

double

The lifetime budget in revenue. The revenue currency is defined by the currency field.

Only applicable to non-seamless insertion orders.

null (unlimited)

 

lifetime_budget_imps

int

The lifetime budget in impressions. Note: If you add line items to this insertion order, any spend already associated with those line items before they are added to the insertion order is NOT counted against the lifetime budget of the insertion order. Only spend that occurs while the line item is a child of the insertion order is counted.

Only applicable to non-seamless insertion orders.

null (unlimited)

 

enable_pacing

boolean

If true, then spending will be paced over the course of the day. Only applicable if there is a daily_budget.

Only applicable to non-seamless insertion orders.

N/A

 

lifetime_pacing_span

int

In the event of an underspend event, this indicates the number of days across which the underspent amount will be distributed.

Only applicable to non-seamless insertion orders.

null (3 days)

 

daily_budget

double

The daily budget in revenue. The revenue currency is defined by the currency field. Note: if you add line items to this insertion order, any impressions associated to those line items when they are added to the insertion order are NOT counted under the lifetime budget of the insertion order. Only impressions that occur while the line item is a child of the insertion order are counted.

Only applicable to non-seamless insertion orders.

null (unlimited)

 

daily_budget_imps

int

The daily budget in impressions.

Only applicable to non-seamless insertion orders.

null (unlimited)

 

lifetime_pacing_pctdouble

A double integer between (and including) 50 and 150, used to set pacing throughout the insertion order's lifetime. Possible values can be any double between 50 and 150 on the following scale:

  • 50 - Pace behind schedule
  • 100 - Pace evenly
  • 150 - Pace ahead of schedule

Only applicable to non-seamless insertion orders.

 

Alpha-Beta Notice

This field or feature is part of functionality currently in either Alpha or Beta phase. It is therefore subject to change.

100 
profile_id
int

Specifies the ID of the profile attached to the seamless insertion order (i.e., must use budget_intervals). A profile can be used to define how inventory is targeted and/or how frequency capping is enforced (see Profile Service for details). A profile can also be set at the advertiser, line item, campaign, and creative levels. The most restrictive setting always takes precedence. 

N/A 
stats

object

The stats object has been deprecated (as of October 17, 2016). Use the Report Service to obtain statistical information instead.

N/A

 

object_stats

object

Read-only. The number of total, active, and inactive line items under the insertion order. To include this object in a GET response, pass object_stats=true in the query string.

N/A

 

viewability_standard_providerstring

This field determines what standard to measure viewability against (for example, 50% of pixels in view for 1 continuous second). Currently, the only possible value is iab.

This field cannot be edited, and only appears on seamless insertion orders.


'iab' 

Line Items

Each object in the line_items array contains the following fields.

Field

Type

Description

id

int

The numeric ID associated with this line item. Required on POST or PUT.

line_item_typeenum

The type associated with the child line item. Possible values are:

  • "standard_v1" - Denotes that the child line item is a standard line item.
  • "standard_v2" - Denotes that the child line item is an augmented line item.
  • "guaranteed" - Denotes that the child line item is a guaranteed line item.
  • "performance" - This line item type has been deprecated.
namestringThe name of the line item.

code

string

If you have chosen to associate an optional identifying name (a "code") with this line item, it will show up here.

state

string

Line items can be "active" or "inactive". Campaigns under inactive line items will not serve.

start_date

date

The date when campaigns under this line item start serving.

end_date

date

The date when campaigns under this line item stop serving.

timezone

string

The timezone with which the line item and its campaigns are set to. This will affect the start_date and end_date.

Labels

You can use the read-only Label Service to view all possible labels for line items, advertisers, insertion orders, campaigns, and publishers. This service also allows you to view the labels that have already been applied to your insertion order.

Field

Type

Description

value

string (100)

The value assigned to the label. For example, for the "Sales Rep" label, this could be a name such as "Michael Sellers".

id

int

The ID of the label. Required on POST or PUT.

name

enum

The name of the label. Possible values:

  • "Trafficker"
  • "Sales Rep"
  • "Campaign Type"

Broker Fees

Each object in the broker_fees array contains the following fields.

Field

Type

Description

broker_id

int

The ID of the broker.

payment_type

enum

Type of payment to the broker. Possible values:

  • "cpm"
  • "revshare"

value

double

The value of the payment, based on the payment type.

description

string (255)

The free-form description of the broker fee entry.

Budget Intervals

This array is only used for seamless insertion orders. 

Consider the following when using the budget_interval array:

  • Budget intervals must contain a start_date and end_date.
  • Date ranges (i.e., start_date, end_date) of different budget intervals on the same insertion order cannot overlap.
  • Budget intervals must contain a lifetime_budget or lifetime_budget_imps.
  • Budget intervals cannot be used if budget fields on the insertion_order object itself are set.
  • Edits made to the budget interval (e.g., start or end dates) on the insertion order must be manually replicated on all child line items (using the line-item service). 
    • For standard line items, use the parent_interval_id  to link the line item to its parent insertion order. Budget interval dates will automatically be inherited by the line item once that association is made. See Line Item Service
    • For augmented line items (ALI), ensure that start and end dates of each budget interval fall within the dates of the parent insertion order's budget intervals. See Line Item Service (Augmented)
  • A maximum of 52 budget intervals may be created per insertion order. 
  • If you want the budget interval to have an unlimited budget, all 4 budget fields in the array (lifetime_budget, lifetime_budget_imps, daily_budget and daily_budget_imps) must be set to null. This is only allowed if the lifetime_pacing field is set to "false".

Each object in the budget_intervals array contains the following fields.

Field

Type

Description

id

int

The ID of the budget interval.
start_datetimestampThe start date of the budget interval. Format must be YYYY-MM-DD hh:mm:ss (hh:mm:ss must be set to 00).
end_datetimestamp

The end date of the budget interval. Format must be YYYY-MM-DD hh:mm:ss (hh:mm:ss must be set to 23:59:59). If this field is set to null, then the insertion order's budget interval will run indefinitely. If you set this field to 'null':

  • there may not be more than one object in the budget_intervals array (i.e., maximum of 1 budget interval)
  • the lifetime_pacing field must set to "false"
  • the "daily_budget" field must be set to null.
timezonestring

The timezone by which budget and spend are counted. For a list of acceptable timezone values, see API Timezones. The default value is "EST5EDT" or the advertiser's timezone.

codestringThe custom code for the budget interval. The code may only contain alphanumeric characters, periods, underscores or dashes. The code you enter is not case-sensitive (upper- and lower-case characters are treated the same).
lifetime_budgetdouble

The lifetime budget in revenue for the budget interval. The revenue currency is defined by the currency field on the insertion_order object.

This field defaults to null (unlimited).

If you also set the lifetime_budget_imps field within this array, whichever budget is exhausted first will cause spending to stop. Best practice is to only set one of these fields.

lifetime_budget_impsint

The lifetime budget in impressions for the budget interval. Note: if you add line items to this insertion order, any spend already associated with those line items before they are added to the insertion order is not counted against the lifetime budget of the insertion order. Only spend that occurs while the line item is a child of the insertion order is counted.

This field defaults to null (unlimited).

If you also set the lifetime_budget field within this array, whichever budget is exhausted first will cause spending to stop. Best practice is to only set one of these fields.

lifetime_pacing boolean

If true, the insertion order will attempt to pace the lifetime budget evenly over the budget interval. If true:

  • You must establish a lifetime_budget or lifetime_budget_imps 
  • You must establish a start_date and end_date
  • You cannot set a daily_budget
  • You cannot set enable_pacing to false
daily_budget double

This field defaults to null (unlimited). Instead, use the line item to set this value.

If you also set the daily_budget_imps field within this array, whichever budget is exhausted first will cause spending to stop. Best practice is to only set one of these fields.

daily_budget_impsint
This field defaults to null (unlimited). Instead, use the line item to set this value.

If you also set the daily_budget field within this array, whichever budget is exhausted first will cause spending to stop. Best practice is to only set one of these fields.

enable_pacingboolean

If true, then spending will be paced over the course of the day. Only applicable if there is a daily_budget.

lifetime_pacing_pctdouble

Set this field to 100 (the default) and then use the line item to set lifetime pacing.

A double integer between (and including) 50 and 150, used to set pacing throughout a budget interval. Possible values can be any double between 50 and 150 on the following scale:

  • 50 - Pace behind schedule
  • 100 - Pace evenly
  • 150 - Pace ahead of schedule

Stats

The stats object has been deprecated (October 17, 2016). Instead, use the Report Service to obtain statistical information.

Examples

Adding a new seamless insertion order with budget intervals
Adding a new non-seamless insertion order 
Viewing all insertion orders for advertiser 11
 Deleting a budget interval (on a seamless insertion order)
 Modifying a budget interval (on a seamless insertion order)

Related Topics