Skip to end of metadata
Go to start of metadata

Line Item Service (Augmented Line Item - ALI)

Augmented Line Items are currently in Open Beta. This page describes the Line Item Service for augmented line items. It links to other API documentation which is designed for legacy line items and may mention fields and objects that are not used with augmented line items. Most importantly, augmented line items can only be used with seamless insertion orders, not legacy insertion orders which don't support budget intervals (i.e., don't use the budget_intervals array). To create an augmented line item, you must set the line_item_type field to 'standard_v2' and associate the line item with a seamless insertion order via the insertion_orders array.

A line item defines your financial relationship with an advertiser, including budget, revenue type, performance goals, bidding strategies, and inventory targeting. The augmented line item must be used with the seamless insertion order. We suggest that you streamline your setup for long-standing advertiser relationships by adding budget intervals to your insertion orders.

On This Page

REST API

Add a new line item:

Modify an existing line item:

View all of an advertiser's line items:

View multiple line items by ID using a comma-separated list:

Helpful Query String Filters

  • You can filter for line items based on when they first and last served. This is particularly useful when you are approaching your object limit and need to identify line items that can be deleted from the system. For more details, see First Run / Last Run.
  • You can filter for line that are not serving due to various conditions. For more details, see Alerts.

Search for line items with IDs or names containing certain characters:

Delete a line item:

Deletion is Recursive and Permanent

Deleting a line item will also delete all of its  impression trackers and clicktrackers. The deletions are permanent and cannot be reverted. Although deleted objects continue to be available in reporting, you will no longer have visibility into their specific settings (e.g., revenue budget, tracking, cost budget and targeting).

Find out which fields you can filter and sort by:

About Performance Goals

Performance goals are used to track and measure performance when the revenue_type and the goal_type are not measured the same way. For example, a revenue_type of "cpm" might be matched with a goal_type of "cpa" because the advertiser wants to measure goal achievement in terms of conversions but pay in CPM.

  • CPA: To set performance goals for line items with goal_type "cpa", use both the goal_pixels array and the valuation object. The goal_pixels array contains information about CPA goal targets and thresholds. See CPC below for a basic explanation of the valuation object.
  • CPC: To set performance goals for line items with the goal_type "cpc", use the valuation object. The valuation object contains the performance goal threshold, which determines the bid/no bid cutoff on optimized line items, and the performance goal target, which represents the desired clicks or click-through rate. See the description of the valuation object below for more details on which fields to set.

To learn more about performance goals, see Understanding Performance Goals.

JSON Fields

General

Field

Type (Length)

Description

Default

Required On

id

int

The ID of the line item.

 

PUT, in query string

code

string (100)

A custom code for the line item. 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., insertion orders or line items) can use the same code per advertiser. For example, 2 line items cannot both use code "XYZ", but a single insertion order and its child line item can.

null

 

name

string (100)

The name of the line item.

 

POST

advertiser_id

int

The ID of the advertiser to which the line item belongs.

  

state

enum

The state of the line item. Possible values: "active" or "inactive".

"active"

 
line_item_typeenum

The type of line item. Possible values are:

  • "standard_v1" - standard line item (non-ALI)
  • "standard_v2" - augmented line item (ALI).
  • "guaranteed_delivery" - guaranteed line item (GDLI)

Note: Ensure this field is set to "standard_v2" for ALIs.

"standard_v2" 

start_date

timestamp

Do not use this field. Instead, use the start_date and end_date fields within the budget_intervals array to designate when the line item should run.

null (immediately)

 

end_date

timestamp

Do not use this field. Instead, use the start_date and end_date fields within the budget_intervals array to designate when the line item should run.

null (indefinitely)

 

timezone

enum

The timezone by which budget and spend are counted. See API Timezones for details and accepted values.

NOTE: For ALIs, be sure to use this field (and not the one in the budget_intervals array) to set the line item's time zone.

"UTC" or advertiser's timezone

 
ad_typesarray of strings

The type of creative used for this line item.  Possible values: 

  • "banner"
  • "video" (includes audio types as well)
  • "native"

The array should only have a single value. This value determines how auction items are tracked for the line item's buying strategy, paying strategy, optimization options, creative association, and targeting options. 

All creatives associated to a line item must have the same ad type, which should match the ad_types selected here.

"banner"POST/PUT
discrepancy_pctdoubleDeprecated.  

publishers_allowed

string

Specifies the type of inventory to bid on with this line item. Possible values: real_time or direct . Real-time line items may target inventory that is exposed for RTB by other AppNexus members or by our inventory supply partners. Direct line items may only target publisher inventory within your network.

  

revenue_value

double

The amount paid to the network by the advertiser.

Depending on what you set the revenue_type field to, this field must be set to the actual value of that revenue type (e.g., the desired CPC). If your revenue_type is "cost_plus_margin", set this field to the percentage margin your client pays you (e.g., .20 for 20%).

 

POST/PUT

revenue_type

enum

The way the advertiser has agreed to pay you (also called Booked Revenue). Possible values are listed below.

  • "cpm" - Select this value if you are being paid flat payment for 1000 impressions (CPM), per click (CPC) or per view (Viewable CPM:
    • If CPM, set this to "cpm", the revenue_value field to the CPM value and set the max_avg_cpm and min_avg_cpm fields to null.
    • If CPC, set this to "cpm", the revenue_value field to the CPC value and set "revenue_auction_event_type" to "click", "revenue_auction_event_type_code" to "click" and "revenue_auction_type_id" to 3.
    • If Viewable CPM, set this to "cpm", the revenue_value field to the Viewable CPM value, the revenue_auction_event_type field to "view", the revenue_auction_event_type_code field to "view_display_50pv1s_an" and "revenue_auction_type_id" to 2. Only measured viewable impressions will be counted, according to AppNexus viewability measurement, using the IAB definition.
  • "vcpm" - A dynamic CPM (where Booked Revenue is equal to the cost of the impression before bid reduction). If "vcpm" is selected here, goal_type has been set to 'none', and no 'expected_value' model has been attached, you must set a 'max_avg_cpm' value.
  • "cost_plus_margin" - Media cost (what you spend on inventory) plus a percentage of what you spend. If selected, you must also set the revenue_value to the percentarge margin you receive (e.g., .2 for 20%). Data costs will also be added if you participate in third-party data clearing (e.g., segments). If you disable optimization for Cost Plus (via the goal_type field), you must set a flat CPM for Cost Plus via the max_avg_cpm field (in the valuation object).

If the lifetime_budget_imps or daily_budget_imps fields are set or the line item's parent insertion order's budget_type is set to impression, then revenue_type may not be set to "CPC".


"none"

 

goal_type

enum

For line items that make use of performance goals. Possible values: null, "cpc", "cpa", or "custom"

  • If you want to optimize to both CPC and CPA performance goals, set this field to "cpa". You must also set the goal_target and goal_threshold fields (in the valuation object) to your CPC goal and the post_click_goal_target and post_click_goal_threshold fields (in the goal_pixels array) to your CPA goal.
  • If you want to optimize to a CPC goal but track against a CPA goal, set this field to "cpc". You must also set the goal_target and goal_threshold fields (in the valuation object) to your CPC goal and the post_click_goal_target and post_click_goal_threshold fields (in the goal_pixels array) to your CPA goal.
  • If you want to optimize to a CPC goal but NOT track against a CPA goal, set this field to "cpc". You must also set the goal_target and goal_threshold fields (in the valuation object) to your CPC goal and set goal_pixels to null.
  • If you want to optimize to a Viewable CPM goal, set this field to null. You must also set the goal_target and goal_threshold fields (in the valuation object) and goal_pixels to null. In addition, you must also set the following fields in the auction_event object: kpi_auction_event_type, kpi_auction_event_type_code, kpi_auction_type_id and kpi_value.
  • If you want to upload your own custom EV model (Expected Valuation), as opposed to a click_imp or ev_click model, set this field to "custom". See Conditonal Component Models for details.
  • If you want to disable optimization, set this field to null. In addition, for PUT calls, if the line item was previously set to optimize to a Viewable CPM, you must also set the following fields (in the auction_event object) as follows:
    • "kpi_auction_event_type":"impression"
    • "kpi_auction_event_type_code":"impression"
    • "kpi_auction_type_id":1
    • "kpi_value":null

"none"

 

goal_value

double

Deprecated. Use valuation object instead. See Valuation below for details.

  

last_modified

timestamp

Read-only. The time of last modification to this line item.

  

click_url

string (1000)

The click URL to apply at the line item level.

  

currency

string (3)

The currency used for this line item. For a list of supported currencies, see the Currency Service.

Once the line item has been created, the currency cannot be changed.

Unable to render {include} The included page could not be found.

Default currency of the advertiser

 

require_cookie_for_tracking

boolean

If true, a cookie is required for conversion tracking.

  

profile_id

int

You may associate an optional profile_id with this line item. A profile is a generic set of rules for targeting inventory. See the Profile Service for details.

  
member_idintID of the member that owns the line item.  

comments

string

Comments about the line item.

  

remaining_days

int

https://wiki.appnexus.com/display/dsp/Add+CreativesRead-only. The number of days between today and the end_date for the line item. Note that this will be null if the start_date is in the future or if either the start_date or end_date is not set.

  

total_days

int

Read-only. The number of days between the start_date and end_date for the line item. Note that this will be null if either the start_date or end_date is not set.

  

advertiser

object

Read-only. An object describing the advertiser with which this line item is associated. For details, see Advertiser below.

  

labels

array

The optional labels applied to the line item. Currently, the labels available are: "Trafficker" and "Sales Rep". See Labels below for more details.

You can report on line item labels with the Network Analytics and Network Advertiser Analytics reports. For example, if you use the "Trafficker" label to specify the name of the trafficker responsible for each line item, you could run the Network Analytics report filtered by "trafficker_for_line_item" to focus on the line items that a particular trafficker is responsible for, or grouped by "trafficker_for_line_item" to rank the performance of your traffickers.

  

broker_fees

array

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.

  

pixels

array of objects

The conversion pixels being used for CPA revenue type. Both post-click and post-view revenue may be specified. You may only attach 20 pixels to a line item. If you need to attach more, please speak with your AppNexus Implementation Consultant or Support. See Pixels below for more details and the example below for a sample of the format.

null

 

insertion_orders

array of objects

Objects containing metadata for the insertion orders this line item is associated with. For more information, see Insertion Orders below.

Once a line item is associated with a seamless insertion order, it cannot be associated to a legacy insertion order.

  

goal_pixels

array

For a line item with the goal_type "cpa", the pixels used for conversion tracking, as well as the post-view and post-click revenue. See Goal Pixels below for more details and the example below for a sample of the format.

  

imptrackers

array of objects

Read-only. The third-party impression trackers associated with the line item. See Impression Tracker Service for more details.

  

clicktrackers

array of objects

Read-only. The third-party click trackers associated with the line item. See Click Tracker Service for more details.

  
valuationobject

For a line item with the goal_type "cpc" or "cpa", the performance goal threshold, which determines the bid/no bid cutoff on optimized line items, and the performance goal target, which represents the desired clicks (conversions for "cpa" are set in the goal_pixels array). See Valuation below for more details.

  
creativesarray of objectsThe creatives that are associated with the line item. See Creatives below for more details.  
budget_intervalsarray of objects

Budget intervals enable multiple date intervals to be attached to a line item, 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 line-item object:

  • lifetime_pacing
  • lifetime_budget
  • lifetime_budget_imps
  • enable_pacing
  • lifetime_pacing_span
  • allow_safety_pacing
  • daily_budget
  • daily_budget_imps
  • lifetime_pacing_pct
  

lifetime_budget

double

Do not use this field. Instead, use the budget fields within the budget_intervals array.

null (unlimited)

 

lifetime_budget_imps

int

Do not use this field. Instead, use the budget fields within the budget_intervals array.

null (unlimited)

 

daily_budget

double

Do not use this field. Instead, use the budget fields within the budget_intervals array.

null (unlimited)

 

daily_budget_imps

double

Do not use this field. Instead, use the budget fields within the budget_intervals array.

null (unlimited)

 

enable_pacing

boolean

If true, the daily budgeted spend is spread out evenly throughout a day. Only applicable if there is a daily budget. That's why it defaults to true if daily budget is set; otherwise, it defaults to null.

null

 

allow_safety_pacing

boolean

Deprecated. This field may not be set.

  

lifetime_pacing

boolean

If true, the line item will attempt to spend its overall lifetime budget evenly over the line item flight dates. If true, you cannot set a daily_budget, you cannot set enable_pacing to false, and you must first establish a lifetime_budget, a start_date, and an end_date for the line item.

null

 

lifetime_pacing_span

int

Do not use use or edit the value of this field.

null (3 days)

 
lifetime_pacing_pctdouble

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
100 
payout_margindoubleThe payout margin on performance offer line items. POST, if performance_mkt_crossnet in the valuation object is true

insertion_order_id

int

The ID of the current active insertion order (when applicable). Must append include_insertion_order_id=true to return this field in a GET call. See the Insertion Order Service for details.

  

stats

object

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

  

all_stats

array

Read-only. To show Console Rapid Reports for all available intervals (today, yesterday, the last 7 days, life time), pass all_status=true in the query string of a GET request.

  

first_run

timestamp

Read-only. The date and time when the line item had its first impression, refreshed on an hourly basis. This value reflects the UTC time zone. To include this information in a GET response, pass flight_info=true in the query string. For details about how to filter line items based on when they first served, see First Run / Last Run below.

  

last_run

timestamp

Read-only. The date and time when the line item had its last impression, refreshed on an hourly basis. This value reflects the UTC time zone. To include this information in a GET response, pass flight_info=true in the query string. For details about how to filter line items based on when they last served, see First Run / Last Run below.

  

expected_pacing

double

Deprecated.

The   stats object and Quickstats have been deprecated (as of October 17, 2016).

  

total_pacing

double

Deprecated.

The stats object and Quickstats have been deprecated (as of October 17, 2016).

  

has_pacing_dollars

enum

Deprecated.

The stats object and Quickstats have been deprecated (as of October 17, 2016).

  

has_pacing_imps

enum

Deprecated.

The  stats  object and Quickstats have been deprecated (as of October 17, 2016).

  

imps_pacing_percent

int

Deprecated.

The  stats  object and Quickstats have been deprecated (as of October 17, 2016).

  

rev_pacing_percent

int

Deprecated.

The  stats  object and Quickstats have been deprecated (as of October 17, 2016).
  

alerts

object

Read-only. The conditions that are preventing the line item from serving. There are two types of alerts: pauses and warnings. Pauses are considered intentional and user-driven, whereas warnings are considered unintentional. To retrieve line items based on pauses, you must pass certain query string parameters in the GET request. For more details, including a complete list of possible pauses, see Alerts below.

  

inventory_type

enum

The type of inventory targeted by this line item. Possible values: "real_time", "direct", or "both". "Real-time" includes all third-party inventory not managed by your network that has been enabled for reselling (including external supply partners such as Microsoft Advertising Exchange and Google AdX). "Direct" includes only inventory managed by your network.

Although you can continue to use this field, the fields within supply_strategies object are the preferred mechanism for designating inventory supply sources. However, once you set any of the boolean fields within supply_strategies object to true, the value of the inventory_type field will be permanently ignored and unsettable for that augmented line item.

"real_time"

 
supply_strategiesobjectAn object containing several boolean fields used to designate which inventory supply sources you would like to target. The values of this object's boolean fields supersede the setting of the inventory_type field and once set will cause the inventory_type field to be permanently locked and ignored. For more details, see Supply Strategies below.  
creative_distribution_typeenum

When multiple creatives of the same size are trafficked via a line item, this field's setting is used to determine the creative rotation strategy that will be used. Allowed values:

  • even: Even rotation is handled by automatically by our system. 
  • weighted: Creative rotation is based on a user-supplied weight.
  • ctr-optimized: The creative in the size bucket with the highest CTR delivers the most. The default.  
  • split: Rotation is based on a user-supplied weight defined per split. Note that the weights assigned to the splits themselves, not the creatives. That is, if a split has an allocation of 50%, 50% of impressions will go that split. If multiple creatives are associated with a split, impressions are distributed evenly among the associated creatives.
"even" 
prefer_delivery_over_performanceboolean

This field is used to indicate your goal priority (whether you wish to give greater priority to deliver, perfomance or margin). Options are:

  • true - Select this option to ensure delivery of your desired impression volume. This may deprioritize your performance (e.g., clicks) or profit margin.
  • false - Select this option to do one of the following:
    • prioritize performance (e.g., clicks). This may deprioritze your impression volume (delivery) and profit margin. You must also set min_margin_pct (in the valuation object) to null.
    • prioritize meeting your desired margin. This may deprioritize delivery and performance. If you select this option, you must also set the min_margin_pct field (in the valuation object) to your desired margin (e.g. 10 for 10%)
false 
viewability_vendorstring

This field determines what provider measures the viewability of the ad unit. The only value that is currently valid is "appnexus".

"appnexus" 
is_archivedboolean

Read-only. Indicates whether the line item has been automatically archived due to not being used. Once set to true, the value can't be changed and the only calls that can be made on the line item object are GET and DELETE.

If a line item is automatically archived, its profile will also be archived and the only calls that may be made on either of those objects are  GET  and  DELETE . In addition, once archived, the line item may not be associated with any insertion orders.

false 
archived_on timestampRead-only.  The date and time on which the line item was archived (i.e., when the  is_archived field was set to  true ).null 

Budgeting/Pricing

Field

Type

Description

Default

Required On

lifetime_budget

double

The lifetime budget in dollars (media cost). Null corresponds to "unlimited".

If lifetime_budget is set to null (unlimited), and the line item and insertion order lifetime budgets are also set to null, severe overspend can occur.

null

 

lifetime_budget_imps

int

The lifetime budget in impressions. Null corresponds to "unlimited".

null

 

daily_budget

double

The daily budget in dollars (revenue). Null corresponds to "unlimited".

null

 

daily_budget_imps

int

The daily budget in impressions. Null corresponds to "unlimited".

null

 

learn_budget

double

The lifetime budget in dollars (revenue) allocated to learning. Null corresponds to "unlimited".

null

 

learn_budget_imps

int

The lifetime impression budget allocated to learning. Null corresponds to "unlimited".

null

 

learn_budget_daily_cap

double

The maximum number of dollars (revenue) that can be allocated to learning per day. Null corresponds to "unlimited".

null

 

learn_budget_daily_imps

int

The maximum number of impressions that can be allocated to learning per day. Null corresponds to "unlimited".

null

 

enable_pacing

boolean

If true, the line item's daily budgeted spend is spread out evenly throughout each day. This is only applicable if daily_budget is set. For more details about even daily pacing, see Daily Pacing.

false

 

lifetime_pacing

boolean

If true, the line item will attempt to spend its overall lifetime budget evenly over the line item flight dates. If true, you cannot set a daily_budget, you cannot set enable_pacing to false, and you must first establish a lifetime_budget, a start_date, and an end_date for the line item.

false

 

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. The default value of null indicates a value of three (3) days.

null

 
priority

int

For a line item targeting managed inventory (inventory_type is "direct"), since you have already paid for inventory, there is no need to input a buying strategy. However, you can set the line item's priority to weight the line item against other direct line items within your account. The line item with the highest priority will always win, even if a lower priority line item bids more.

5

 

cadence_modifier_enabled

boolean

If true, bids will be adjusted upward and downward based on the frequency and recency of the user. Typically, bids are increased for low frequency-recency impressions and decreased for high frequency-recency users. This feature is based on the idea that the effectiveness of an ad differs when a user hasn't seen the ad before, hasn't seen it many times, or hasn't seen it recently. For more details, see Cadence Modifier.

false

 

expected_pacing

double

Deprecated.

The stats object and Quickstats have been deprecated (as of October 17, 2016).

  

total_pacing

double

Deprecated.

The stats object and Quickstats have been deprecated (as of October 17, 2016).

  

has_pacing_dollars

enum

Deprecated.

The stats object and Quickstats have been deprecated (as of October 17, 2016).

  

has_pacing_imps

enum

Deprecated.

The stats object and Quickstats have been deprecated (as of October 17, 2016).

  

imps_pacing_percent

int

Deprecated.

The stats object and Quickstats have been deprecated (as of October 17, 2016).

  

media_cost_pacing_percent

int

Deprecated.

The stats object and Quickstats have been deprecated (as of October 17, 2016).

  

Supply Strategies

The supply_strategies object is used to designate which supply source you wish to target when buying inventory. It contains 3 boolean fields. You can set any of these fields to true or false to target any combination of Open Exchange, Managed and/or Deals inventory. At least one of these fields must be set to true.

For deals, in addition setting the deals field to true within this object, you must also ensure that you both provide a list of deals to target or exclude in the deal_targets array and set the deal_action_include field to true or false (depending on inclusion or exclusion) in the profile service.

The values of this object's boolean fields supersede the setting of the inventory_type field. Once any of these fields are set to  true  on an ALI, the  inventory_type  field will be ignored and unsettable for that line item. If you attempt to make a  PUT  call on the value of the  inventory_type  field after one or more of these fields have been set to  true , the following error message will be generated:  "inventory_type cannot be updated once supply_strategies has been set"

Field

Type

Description

rtb

boolean

Designates whether you wish to target inventory on the Open Exchange. This includes all third-party inventory not managed by your network that has been enabled for reselling (including external supply partners such as Microsoft Advertising Exchange and Google AdX).

managed

boolean

Designates whether you wish to target managed inventory. This only includes inventory managed by your network.

deal

boolean

Designates whether you wish to target deal inventory. This includes any deals which you are are eligible to bid on.


Target Open Exchange and 2 Deals but not Managed inventory

Advertiser

You can use the Advertiser Service to create or view advertisers.

Field

Type

Description

id

int

The unique identifier for this advertiser.

name

string

The name of the advertiser associated with the unique ID above.

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

Field

Type

Description

id

int

The ID of the label. Possible values: 7, 8, 11.

name

enum

Read-only. The name of the label. Possible values: "Trafficker" or "Sales Rep".

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

Broker Fees

When a network uses a broker to serve an impression, it pays a fee to the broker for that service. This value varies between different networks, different brokers, and different line items. Therefore, the network must specify how much it will pay each broker it uses. This can also be done at the Insertion Order level (Insertion Order Service).

To create or edit brokers, refer to the Broker Service.

Field

Type (Length)

Description

broker_id

int

The ID of the broker.

broker_name

string

Read-Only. The name of the broker.

payment_type

enum

The type of payment to the broker. Possible values: "cpm" or "revshare".

The payment_type can only be set to " cpm" if the revenue_type is set to " cpm ". Where revenue_type is set to " cpa " or " cpc ", payment_type must be set to " 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.

fee_typeenum

The type of fee. Possible values are "commission" or "serving". Also note:

  • This field may only be set to "serving", if the revenue_type field has been set to 'cost_plus_margin'.
  • This field may only be set to "commission", if the revenue_type field is set to anything other than 'cost_plus_margin'.

Both Serving Fees and Commissions use the same currency as the line item.

Create a Broker Fee
Modify a Broker Fee

Pixels

Each object in the pixels array includes the following fields:

Field

Type

Description

id

int

The ID of the conversion pixel.

state

enum

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

post_click_revenue

double

The post click revenue value for the pixel.

post_view_revenue

double

The post view revenue value for the pixel.

name

string

Read-only. The name of the conversion pixel.

trigger_type

enum

Read-only. The type of event required for an attributed conversion. Possible values: "view", "click", or "hybrid".

Insertion Orders

Field

Type

Description

id

int

The unique ID of the insertion order.

Once a line item is associated with a seamless insertion order, it cannot be associated to a legacy insertion order.

state

enum

The state of this insertion order: "active" or "inactive."

code

string

An optional custom code used to identify this insertion order.

name

string

The name of this insertion order.

advertiser_id

int

The unique identifier of the advertiser associated with this insertion order.

start_date

date

The start date for this insertion order.

end_date

date

The end date for this insertion order.

timezone

enum

The timezone that this insertion order is associated with. See API Timezones for a list of allowed values.

last_modified

date

The date at which this insertion order object was last updated.

currency

enum

The currency type associated with this insertion order. For a list of supported currencies, see the Currency Service.

For best results, set the currency on the parent insertion order. See Insertion Order Service for more information.
budget_intervalsarray of objects

The metadata for the budget intervals from the associated insertion order. Budget intervals enable multiple date intervals to be attached to an insertion order, each with corresponding budget values. See Insertion Order Service for more information.

Valuation

The valuation object is used to set performance goals for line items with the goal_type of "cpc" or "cpa". It contains the performance goal threshold, which determines the bid/no bid cutoff on optimized line items, and the performance goal target, which represents the desired clicks or conversions.

The valuation object contains the following fields:

Field

Type

Description

Default

min_margin_pct

decimal

Only set this field if you have set prefer_delivery_over_performance to false and revenue_type has not been set to cost_plus_margin. Set this to your desired minimum margin (e.g., 10 for 10%). This may cause your delivery and performance to be deprioritized.

null

goal_threshold

decimal

The performance goal threshold determines bidding, inventory discovery, and the bid/no bid check on optimized line items. A value is required here when you are optimizing to either a CPC or post-click CPA goal. In either case, enter your CPC goal (not you post-click CPA goal). If you are optimizing to a post-click CPA goal use the post_click_goal_target and post_click_goal_threshold fields in the goal_pixels array.

null

goal_target

decimalDeprecated.

 

campaign_group_valuation_strategy  enum

Deprecated.

 
min_avg_cpmdouble

The value below which the average CPM may not fall. If the max_avg_cpm field is also set, min_avg_cpm serves as a lower bound of a range. You must set this field if you set revenue_type to "vcpm" (Dynamic CPM) or "cost_plus_margin". If you set revenue_type to "cpm" , you must set this field to null.

 
max_avg_cpmdouble

The value above which the average CPM may not rise. If the min_avg_cpm field is also set, max_avg_cpm serves as a upper bound of a range. You must set this field if you set revenue_type to "vcpm" or "cost_plus_margin" If you set revenue_type to "cpm", you must set this field to null.

If you have disabled optimization for Cost Plus (via the goal_type field), you must set a flat CPM for Cost Plus. Use this field to set the flat CPM value.

 

Auction Event

The following fields are contained within the auction_event object. 

Do not supply values for the fields within this object that end in _code or _id. Only supply values for the fields in the auction_event object that end in _type . The object will return the fields ending in _code and _id, but they will be ignored on POST and PUT calls.

FieldTypeDescription
revenue_auction_event_typestring

This field is used in conjunction with the settings of the revenue_type field. Options are:

  • "impression" - use this value when your Revenue Type is CPM, Dynamic CPM or Cost Plus Margin.
  • "view" - use this value when your Revenue Type is Viewable CPM. Only measured viewable impressions will be counted, according to AppNexus viewability measurement, using the IAB definition.
  • "click" - use this value when your Revenue Type is CPC.
revenue_auction_event_type_codestring

This field is used in conjunction with the settings of the revenue_type field. Options are:

  • "impression" - use this value when your Revenue Type is CPM, Dynamic CPM or Cost Plus Margin.
  • "view_display_50pv1s_an" - use this value when your Revenue Type is Viewable CPM.
  • "click" - use this value when your Revenue Type is CPC.
revenue_auction_type_idint

This field is used in conjunction with the settings of the revenue_type field. Options are:

  • 1 - use this value when your Revenue Type is CPM, Dynamic CPM or Cost Plus Margin.
  • 2 - use this value when your Revenue Type is Viewable CPM.
  • 3 - use this value when your Revenue Type is CPC.

kpi_auction_event_type

string

This field is used in conjunction with the settings of the goal_type field. Options are:

  • "impression" - use this value when you are optmizing to CPC, CPA or not using optimization.
  • "view" - use this value when you are optimizing to a Viewable CPM.
  • "click" - use this value when your Revenue Type is CPC.
kpi_auction_event_type_codestring

This field is used in conjunction with the settings of the goal_type field. Options are:

  • "impression" - use this value when you are optmizing to CPC, CPA or not using optimization.
  • "view_display_50pv1s_an" - use this value when you are optimizing to a Viewable CPM.
kpi_auction_type_idint

This field is used in conjunction with the settings of the goal_type field. Options are:

  • 1 - use this value when you are optmizing to CPC, CPA or not using optimization.
  • 2 - use this value when you are optimizing to a Viewable CPM.
kpi_valuedouble

This field is used in conjunction with the settings of the goal_type field. Set this to one of the following:

  • null - if you are optmizing to CPC, CPA or not using optimization.
  • your Viewable CPM goal (e.g., 5).

payment_auction_event_type

string

This field is only relevant if you have set inventory_type to "real_time" (RTB). Options are:

  • "impression" - if you want to pay per impression.
  • "view" - if you want to pay per view. This option is only allowed when you have set your revenue_type field to use either Viewable CPM or Cost Plus (and disabled optimization).
  • "click" - use this value when your Revenue Type is CPC.
payment_auction_event_type_codestring

This field is only relevant if you have set inventory_type to "real_time" (RTB). Options are:

  • "impression" - if you want to pay per impression.
  • "view_display_50pv1s_an" - if you want to pay per view. This option is only allowed when you have set your revenue_type field to use either Viewable CPM or Cost Plus (and disabled optimization).
payment_auction_type_idint

This field is only relevant if you have set inventory_type to "real_time" (RTB). Options are:

  • 1 - if you want to pay per impression.
  • 2 - if you want to pay per view. This option is only allowed when you have set your revenue_type field to use either Viewable CPM or Cost Plus (and disabled optimization).

Creatives

Each object in the creatives array includes the following fields. To obtain information for "id" or "code" fields you can use the Creative Service.

Field

Type (Length)

  

Description

is_expired

boolean

  

Read-only. If true, the creative is expired. If false, the creative is active.

is_prohibitedboolean  Read-only. If true, the creative falls into a prohibited category on the AppNexus platform.

width

int

  

Read-only. The width of the creative.

audit_status

enum

  

Read-only. The audit status of the creative. Possible values: "no_audit", "pending", "rejected", "audited", or "unauditable" .

name

string

  

Read-only. The name of the creative.

pop_window_maximize

boolean

  

Read-only. If true, the publisher's tag will maximize the window. Only relevant for creatives with format "url-html" and "url-js". If pop_window_maximize is set to true, then neither height nor width should be set on the creative.

heightint  Read-only. The height of the creative.
stateenum  Read-only. The state of the creative. Possible values: "active" or "inactive".
formatenum  Read-only. The format of the creative file. Possible values: "url-html", "url-js", "flash", "image", "raw-js", "raw-html", "iframe-html", or "text".
is_self_auditedboolean  Read-only. If true, the creative is self-audited.
idint  The ID of the creative. Either id or code is required when updating creative association.
codestring  The custom code for the creative. Either id or code is required when updating creative association.
weightintA user-supplied weight that determines the creative rotation strategy for same-sized creatives managed at the line item level. To use this field, the value of creative_distribution_type must be "weighted". Allowed value: an integer greater than 0 and less than or equal to 1000.10 
ad_typestring  

Read-only. The creative ad type. Possible values: "banner", "video", "native".

All creatives associated to a line item must have the same ad type, which should match the ad_types selected for the line item.

Budget Intervals

Budget intervals on an augmented line item must fall within the budget intervals defined on its parent insertion order(s). Budget intervals on line items should have budgets distinct from those of the parent insertion order(s). These function as line item-specific "sub-budgets" of the budget on the corresponding insertion order budget interval.

When creating a new augmented line item, ensure that the start_date and end_date of each of its budget_intervals array objects fall within one of the budget intervals defined on the parent insertion order (insertion orders are associated with line items via the insertion_orders array in the Line Item Service).

The  parent_interval_id  (in the  budget_intervals  array) has been deprecated and its value will be ignored.

Also consider the following when using the budget_interval array:

  • Budget intervals on the same line item cannot overlap.
  • Budget intervals on the line item can have unlimited lifetime budgets (i.e., if all budget fields are left set to null). 
  • Budget intervals cannot be used if budget fields on the top-most level of the line_item object (as described in the General section of this page) itself are set.
  • If you are increasing the budget for the line item's budget interval, you must first increase the budget for the budget interval on the parent insertion order (otherwise you may not have sufficient budget). For more information, see Insertion Order Service.

  • For optimization to work best, your budget intervals should have a duration of at least 4 hours.
  • If line item's parent insertion order's budget_type field is set to impression :
    • the lifetime_budget and daily_budget fields in this array must be set to null
    • use either the lifetime_budget_imps or daily_budget_imps field in this array to set your line item's budget
  • If the line item's parent insertion order's budget_type field is set to revenue :
    • the lifetime_budget_imps and daily_budget_imps fields in this array must be set to null
    • use either the lifetime_budget or daily_budget field in this array to set your line item's budget

Each object in the budget_intervals array contains the following fields.

Field

Type (Length)

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 should be hh:00:00).
end_datetimestampThe end date of the budget interval. Format must be YYYY-MM-DD hh:mm:ss (hh:mm:ss should be set to hh:59:59). For optimization to work best, your budget intervals should have a duration of at least 4 hours. If this field is set to  null , then the line item'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 "lifetime_budget" must be set to null and
  • the "daily_budget" field must be set to a non-null or non-0 value.
timezonestring

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

parent_interval_idintDeprecated. The value of this field will be ignored. Instead, use the start_date and end_date fields of this array to define when the line item should run.
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.

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

lifetime_budget_impsdouble

The lifetime budget in impressions for the budget interval. Note that, 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.

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

lifetime_pacingboolean

If true, the line item will attempt to pace the lifetime budget evenly over the budget interval. If true, you must set lifetime_budget or lifetime_budget_imps

daily_budgetdouble

The daily budget in revenue for the budget interval. The revenue currency is defined by the currency field on the insertion_order object. Note that, 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.

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

daily_budget_impsdouble

The daily budget in impressions.

If the parent insertion order's budget_type field has been set to "impression" and the line items revenue_type field has been set to Viewable CPM, only the viewable impressions count against both line item and insertion order budgets.

If you also set the daily_budget field, 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.

Goal Pixels

The goal_pixels array is used when working with goal_type "cpa" and contains information about performance goal targets and thresholds. Each object in the goal_pixels array includes the following fields:

Field

Type

Description

id

int

The ID of the conversion pixel.

state

enum

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

post_click_goal

double

Deprecated. Use post_click_goal_target and post_click_goal_threshold instead.

post_view_goal

double

Deprecated. Use post_view_goal_target and post_view_goal_threshold instead.

trigger_type

enum

Read-only. The type of event required for an attributed conversion. Possible values: "view", "click", or "hybrid".

post_click_goal_targetdouble

The post-click advertiser goal value for the pixel. If you want to optimize to both CPC and CPA performance goals or only want to optimize to a CPC goal but track against a CPA goal, set this field to your CPA goal value.

post_view_goal_targetdouble

Deprecated . The post-view advertiser goal value for the pixel (comparable to goal_value for goal_type "cpc"). If you want to optimize to both CPC and CPA performance goals or optimize to a CPC goal but track against a CPA goal, ensure this field is set to null.

post_click_goal_thresholddouble

The post-click advertiser goal threshold for the pixel, which determines the bid/no bid cutoff on optimized line items. Cannot be enabled without a target set (comparable to goal_threshold in the valuation object for goal_type "cpc") If you want to optimize to both CPC and CPA performance goals or only want to optimize to a CPC goal but track against a CPA goal, set this field to your CPA goal value.

post_view_goal_thresholddoubleDeprecated . The post-view advertiser goal threshold for the pixel, which determines the bid/no bid cutoff on optimized line items. Cannot be enabled without a target set (comparable to goal_ threshold in the valuation object for goal_type "cpc") If you want to optimize to both CPC and CPA performance goals or optimize to a CPC goal but track against a CPA goal, ensure this field is set to null .

Stats

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

First Run / Last Run

To include the first_run and last_run fields in a GET response, pass flight_info=true in the query string. You can also filter for line items based on when they first and last served, as follows:

Retrieve only line items that have never served
Retrieve only line items that first served on or after a specific date
Retrieve only line items that first served on or before a specific date
Retrieve only line items that first served within a specific date range
Retrieve only line items that last served on or after a specific date
Retrieve only line items that last served on or before a specific date
Retrieve only line items that last served within a specific date range

Fields of the type date can be filtered by nmin and nmax as well. The nmin filter lets you find dates that are either null or after the specified date, and the nmax filter lets you find dates that are either null or before the specified date.

Alerts

This field notifies you of conditions that are preventing the line item from serving. There are two types of alerts: pauses and warnings. Pauses are considered intentional and user-driven, whereas warnings are considered unintentional.

To retrieve line items based on pauses, you must pass certain query string parameters in the GET request. See below for use cases with query string parameters and examples. Note that you can use these query string parameters both when retrieving all line items or specific line items, but the examples below only cover retrieving all line items, as that is where this feature offers the most value.

Retrieve all line items and show alerts
Retrieve only line items that have at least one pause
Retrieve only line items that have no pauses
Retrieve only line items that have a specific pause
Retrieve only line items that have two or more specific pauses
Pauses

ID

Description

1

State is set to inactive.

2

Flight start is in the future.

4

Flight end is in the past.

Examples

Update a line item to use a CPC performance goal

Update a line item to use both a CPC and CPA performance goal

View a line item

View all of an advertiser's line items

Create a Line Item with a revenue type of Dynamic CPM and optimized to a CPC goal

Create a Line Item with a Revenue Type of Viewable CPM and optimized to both a CPC and CPA goal

Update a line item to optimize to a Viewable CPM goal

Update a line item to use a Revenue Type of Viewable CPM

Update a line item to use a Revenue Type of CPC

Update a line item to use a Revenue Type of Cost Plus Margin (paying a flat CPM) and disable optimization

Update a line item to disable optimization

Related Topics