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. Xandr suggests using insertion orders and budget intervals.

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, 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) 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) 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" in the Finance documentation (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

For augmented line items (ALIs):

Broker fees are deprecated for augmented line items. Please create partner fees and apply them to the line item using the Partner Fee Service.

For standard line items:

  • Broker fees created on an insertion order only apply to standard line items. If you also use augmented line items, you will need to create and apply partner fees to ALIs using the Partner Fee Service.
  • Broker fees at the line item level override broker fees at the insertion order level.

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.


 

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

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


'iab' 
political_contentarray

Information about political advertising conducted with this insertion order. Political advertising must be enabled on the Advertiser Service for this array to be editable. If political advertising is enabled on the Advertiser service, this field is required. (That is, on the Advertiser Service, is_running_political_ads is true.)

For more information about this array, see Political Content.

  

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

start_date

date

The date when line items start serving.

end_date

date

The date when line items stop serving.

timezone

string

The timezone with which the line item is 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, 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

For augmented line items (ALIs):

Broker fees are deprecated for augmented line items. Please create partner fees and apply them to the line item using the Partner Fee Service.

For standard line items:

  • Broker fees created on an insertion order only apply to standard line items. If you also use augmented line items, you will need to create and apply partner fees to ALIs using the Partner Fee Service.
  • Broker fees at the line item level override broker fees at the insertion order level.


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

Political Content

This array will only be editable if is_running_political_ads is true on the Advertiser Service. These fields must be filled out if you are using this insertion order for advertising related to an election, ballot initiative, or political candidate in the United States.

Field

Type

Description

billing_name

 string Read-only. The name of the person or organization that is purchasing ads on Xandr. This will be automatically filled out with the name of the Xandr member.
billing_address_1 string(255)Required. The street address for the person or organization that is purchasing ads on Xandr.
Default value: member billing address
Enter the contact details for the person or team who can best answer any questions about political advertising on this insertion order.
billing_address_2 string(255)

Optional additional line for the billing address for the person or organization that is purchasing ads on Xandr.

billing_city string(100)

Required. City of the billing address for the person or organization that is purchasing ads on Xandr.

Default value: member city

billing_region string(50)

Required. State or region of the billing address for the person or organization that is purchasing ads on Xandr.

Default value: member region

billing_postal_code string(50)

Required. ZIP or postal code of the billing address for the person or organization that is purchasing ads on Xandr.

Default value: member postal code

billing_country string(50)

Required. Country of the billing address for the person or organization that is purchasing ads on Xandr. Country code must be specified with the 3-letter country code. See Country Service for more information.

Default value: member country

billing_phone_code string(10)

Required. Country code for the phone number for the person or organization that is purchasing ads on Xandr.

Default value: member phone code

billing_phone string(50)

Required. Contact phone number for the person or organization that is purchasing ads on Xandr.

Default value: member phone

us_fecid string(50)Required. ID number assigned by the U.S. Federal Election Committee.
organization_name string(100)Required. Name of the person, group, organization, or business that is advertising (the client that is paying you). For example, a candidate, an agency, or a political consultant.
organization_address_1 string(255)Required. Address of the person, group, organization, or business that is advertising. For example, a candidate, an agency, or a political consultant.
organization_address_2 string(255)Optional second line for the address of the person, group, organization, or business that is advertising.  
organization_citystring(100)Required. City in the address of the person, group, organization, or business that is advertising.  
organization_regionstring(50)Required. State or region in the address of the person, group, organization, or business that is advertising.  
organization_postal_codestring(50)Required.  ZIP or postal code of the person, group, organization, or business that is advertising.  
organization_countrystring(50)Required. Country of the person, group, organization, or business that is advertising.  
organization_phone_codestring(10)Required. Country code for the phone number of the person, group, origanization, or business that is advertising.
organization_phonestring(50)Required. Phone number of the person, group, organization, or business that is advertising.
treasurer_name string(100)Required. Treasurer for the committee purchasing the ads. 
payment_method_type enum(1)

Required. How the political organization pays you. Options are:

  • "Direct Debit"
  • "Check"
  • "Credit Card"
  • "Other". If this is selected, payment_method_other is required.

political_objective

 string(255)Required. The candidate or ballot initiative that is supported or opposed.
payment_method_other string(50)Required if "4" (Other) is selected for payment_method_type. Details of how you are being paid for political advertising. 
is_independent_expenditure_committee Boolean

Required. Specifies whether any ads are being paid for by an independent expenditure committee: That is, a third party that spends money on political communications that expressly advocate the election or defeat of a clearly identified candidate and does not coordinate with a candidate, a candidate’s authorized committee, or an agent of the candidate.

registration_form  array Not yet available. New York State and New Jersey require copies of state registration forms from independent expenditure committees making purchases. Creatives won’t serve in New York State or New Jersey until the form is uploaded.
 

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