Skip to end of metadata
Go to start of metadata

Line Item Service

The line items under an insertion order represent the agreed upon strategies you will be executing for the advertiser. After setting up a line item and optionally (depending on whether the advertiser uses insertion orders) associating it to one or more insertion orders, you can create campaigns to specify how to spend the money to fulfill your agreement. Line items are where you will record "booked revenue" using the revenue_type and revenue_value fields, which describe the revenue type (CPM, CPA, etc.) and amount that you will be paid by your advertisers.

Insertion orders will eventually be mandatory. Therefore, as a best practice, AppNexus encourages you to begin using insertion orders as part of your API implementation.

AppNexus suggests associating your line items with insertion orders to preserve historical pacing and performance data across line items under a single insertion order, and to streamline your setup for long-standing advertiser relationships by adding budget intervals to an insertion order. Line items can be associated to one or more insertion orders, but only to those of the same type (an insertion order that uses budget intervals or one that does not). Each line item is associated with one or more child campaigns; bidding strategies and inventory targeting are then set at the campaign level.

Seamless line items

There are two types of line items: seamless and non-seamless (legacy). The main difference between seamless and non-seamless line items is that seamless line items use the budget_intervals array and non-seamless line items do not. In terms of setup, the main differences are:

  • To create an seamless line item, you must: 
    • associate the line item to each insertion order by specifying the IDs of the parent seamless insertion orders in the insertion_orders array.  Each object in the array should have an id field whose value corresponds to one of the parent seamless insertion orders. This associates the line item with each of those insertion orders. You may not associate seamless line items with non-seamless insertion orders.

    • use the parent_interval_id field in the budget_intervals array to specify each budget interval defined on all insertion orders associated with the line item. This will determine when the line item runs.

    • leave the start_date and end_date fields (and any budget or pacing related fields) on the top-level line item object level set to null.

    • only associate seamless line items with seamless insertion orders.

You should also use the budget and pacing related fields in the budget_intervals array to specify the budget available to the line item during each budget interval and how the spending of that budget should be paced.
  • To create a non-seamless line item, you must:
    • use the budget and pacing related fields and the start_date and end_date fields on the main line item 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.

    • leave all fields in the budget_intervals field (and any fields in its array) set to null. You may not associate non-seamless line items with seamless insertion orders.
    • only associate non-seamless line items with non-seamless insertion orders.

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

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

About Performance Goals

Performance goals are also set on the line item. They are used to track and measure campaign performance when an advertiser has articulated performance goals and 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 "ctr" because the advertiser wants to measure goal achievement in terms of the click-through rate but pay in CPM.

To set performance goals for line items with goal_type "cpa", use the goal_pixels array. This array contains information about performance goal targets and thresholds. To set performance goals for line items with the goal_type "cpc" or "ctr", use the valuation object. This object contains the performance goal threshold, which determines the bid/no bid cutoff on optimized campaigns, and the performance goal target, which represents the desired clicks or click-through rate.

To learn more about performance goals, see Understanding Performance Goals (customer login required).

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 child campaigns, 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 and tracking for line items, cost budget and targeting for campaigns).

Find out which fields you can filter and sort by:

JSON Fields

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

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.

N/APOST
state

enum

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

"active"

 
start_date

timestamp

The date and time when the non-seamless line item should start serving. This value reflects the Advertiser's time zone.

If you are creating a seamless line item, do not set this field.

null (immediately)

 
end_date

timestamp

The date and time when the non-seamless line item should stop serving. This value reflects the Advertiser's time zone.

If you are creating a seamless line item, do not set this field.

Dates are inclusive; for example, an end_date of May 4th means the campaign runs until 23:59:59 on May 4th

null (indefinitely)

 
timezone

enum

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

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 
discrepancy_pct
doubleDeprecated.  
publishers_allowed

string

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

  
revenue_value

double

The amount paid to the network by the advertiser.

This field must be set under certain conditions, but may not be set in others. In addition to the POST/PUT requirements listed in the Required On column, please note the following:

  • The field may be populated when revenue_type is cpm, cpc, cpa, cost_plus_margin, cost_plus_cpm, est_cpm. However, if the revenue_type is "cpa" this field will be ignored because revenue is tracked via post_view_revenue or post_click_revenue on the pixel.
  • The field may not be populated when revenue_type is "none" or "vcpm".
 

POST/PUT, if performance_offer and performance_mkt_crossnet in the valuation object are true, and revenue_type is " cpc ".

POST/PUT, if revenue_type is " flat_fee ".

If "flat_fee_type" is "daily" this is the value paid out per day. If "flat_fee_type" is "one_time" this is the value paid out on the final allocation date.
revenue_type

enum

The way the advertiser has agreed to pay you. Possible values are listed below.

If post_view_revenue or post_click_revenue is set for any pixel in the pixels array, revenue_type must be "cpa" .

The revenue_type cannot be set to a value that is incompatible with any of the line item's child campaigns.

  • "none" - Do not track revenue for the line item.
  • "cpm" - A flat payment per 1000 impressions.
  • "cpc" - A flat payment per click.
  • "cpa" - A flat payment per conversion.
  • "cost_plus_cpm" - Media cost (what you spend on inventory) plus an extra CPM.
  • "cost_plus_margin" - Media cost (what you spend on inventory) plus a percentage of what you spend.
  • "flat_fee" - A flat payment that the advertiser will pay you on a specified allocation date. That date can be daily or at the end of the flight. If you pay managed publishers a percentage of your revenue, their share will be paid out on the allocation date, after which the line item will no longer be editable. Note that the flat fee will not be booked on the allocation date unless the line item has served at least 1 impression. If you define a revenue_type of flat_fee you must specify a value for flat_fee_type.
  • est_cpm: the estimated flat payment per 1000 impressions.

"none"

 
goal_type

enum

For line items that make use of performance goals, the way that the advertiser would like to measure campaign optimization. Possible values: "none", "cpc", "cpa", or "ctr".

This field must be set to "none" when performance_offer in the valuation object is true .

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

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

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_id
intID of the line item's owning member.  
comments

string

Comments about the line item.

  
remaining_days

int

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

  
manage_creative
 
boolean

If true, creatives are managed at the line item level. If false, creatives are managed at the campaign level.

This field must be set to true if performance_offer in the valuation object is true .

false 
advertiser

object

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

  
flat_fee

object

A flat payment that the advertiser will pay you on a specified allocation date. That allocation date can be daily or at the end of the flight. If you pay managed publishers a percentage of your revenue, their share will be paid out on the allocation date, after which the line item will no longer be editable. Note that the flat fee will not be booked on the allocation date unless the line item has served at least 1 impression. For more information, see Flat Fee below.

 POST/PUT, if revenue_type is "flat_fee"
flat_fee_type
array

Flat fees can be paid out daily or on the flight end date. Available values are:

  • one_time: The fee will be paid on the final allocation date. The associated revenue_value is the value to be paid on that date. The flight cannot be longer than one month.
  • daily: The fee will be paid daily. The associated revenue_value is the daily fee, not the fee for the entire flight.
one_time
POST/PUT if revenue_type is "flat_fee"
labels

array

The optional labels applied to the line item. Currently, four labels are available: "Trafficker", "Sales Rep", and "Campaign Type". 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 non-seamless insertion order. Only seamless insertion orders may be associated with seamless line items. Only non-seamless insertions orders may be associated with non-seamless line items.

  
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.

  
campaigns

array of objects

Read-only. The campaigns that are associated with the line item. See Campaigns below for more details.

To associate a campaign to a line item, use the line_item_id field in the Campaign Service . Please note that no more than 500 campaigns can be associated to a single line item.

  
valuation
object

For a line item with the goal_type "cpc" or "ctr", the performance goal threshold, which determines the bid/no bid cutoff on optimized campaigns, and the performance goal target, which represents the desired clicks or click-through rate. See Valuation below for more details.

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

This array is only relevant to and required for seamless line items (if the line item is non-seamless, leave this field set to null).

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
  
roadblock
objectThe roadblock settings for the line item. See Roadblock below for details.  

lifetime_budget

double

The lifetime budget in revenue. The revenue currency is defined by the currency field. If you don't want to allocate line item budget to this budget_interval, set this field to 0.

Only applicable to non-seamless line items.

null (unlimited)

 
lifetime_budget_imps

int

The lifetime budget in impressions. If you don't want to allocate line item budget to this budget_interval , set this field to 0 .

Only applicable to non-seamless line items.

null (unlimited)

 
daily_budget

double

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

Only applicable to non-seamless line items.

null (unlimited)

 
daily_budget_imps

int

The daily budget in impressions.

Only applicable to non-seamless line items.

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.

Only applicable to non-seamless line items.

null

 
allow_safety_pacing

boolean

If true, spend per minute is limited to a maximum of 1% of the lifetime budget and 5% of the daily budget.

Only applicable to non-seamless line items.

  
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.

Only applicable to non-seamless line items.

null

 
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 line items.

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

Alpha-Beta Notice

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

Only applicable to non-seamless line items.

100 
payout_margin
doubleThe 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.

Only seamless insertion orders may be associated with seamless line items. Only non-seamless insertions orders may be associated with non-seamless line items.

  
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 (customer login required) for all available intervals (today, yesterday, the last 7 days, life time), pass all_status=true in the query string of a GET request.

  
object_stats

object

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

  
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. Note that, at this time, there are no warnings for line items. 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.

  
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. Note that creatives must be managed on the line item in order to use this field. Allowed values:

  • even: The default. Use the standard AppNexus creative optimization algorithm, where each creative's valuation is computed independently, and the best-valued creative is chosen to serve.
  • weighted: Creative rotation is based on a user-supplied weight.
  • ctr-optimized: The creative with the highest CTR delivers the most.
"even" 
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 

Advertiser

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, campaigns, 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", "Sales Rep", or "Campaign Type".

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 campaigns. Therefore, the network must specify how much it will pay each broker it uses. This can also be done at the Campaign level (Campaign Service) or 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.

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 with a non-seamless insertion order. Only seamless insertion orders may be associated with seamless line items. Only non-seamless insertions orders may be associated with non-seamless line items.

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. The default value is "EST5EDT" or the advertiser's timezone.

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 .

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.

Campaigns

Each object in the campaigns array includes the following fields.

Field

Type (Length)

Description

id

int

Read-only. The ID of the campaign.

name

string (100)

Read-only. The name of the campaign.

state

enum

Read-only. The state of the campaign. Possible values: "active", "inactive", or "parent_inactive".

inventory_type

enum

Read-only. The type of inventory targeted by this campaign. 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.

cpm_bid_type

enum

Read-only. The bidding strategy for buying third-party inventory on a per-impression basis. Possible values: "base", "average", "clearing", "predicted", or "margin". Average is equivalent to Estimated Average Price (EAP); clearing is equivalent to Estimated Clear Price (ECP); predicted means you set a CPC goal or CPA goal.

priority
intFor Direct Buying Strategy, the priority for campaigns that buy your own managed inventory. Default is 5.
start_date
dateThe date the campaign starts.
end_date
dateThe date the campaign ends.
creative_count
intThe number of creatives associated with the campaign.
profile_id
intThe ID of the profile associated with the campaign.

Valuation

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

The valuation object contains the following fields:

Field

Type

Description

Default

min_margin_pct

decimalFor line items with revenue_type "cpm", "cpa", or "cpc" the minimum margin PCT.

null

goal_threshold

decimalFor line items with the goal_type "cpc" or "ctr", the performance goal threshold, which determines the bid/no bid cutoff on optimized campaigns.

null

goal_target

decimalFor line items with the goal_type "cpc" or "ctr", the performance goal target, representing the desired clicks or click-through rate.

null

performance_offerboolean

If true, the line item is a performance offer line item. This field is applicable only when revenue_type is "cpc" or "cpa". Note that once set, this field cannot be changed.

To set this field to true, the following requirements must be met:

  • performance_mkt_managed and/or performance_mkt_crossnet (in the valuation object) must be true
  • goal_type must be "none"
  • manage_creative must be true
  • revenue_type must be "cpa" or "cpc"
  • If revenue_type is "cpa", post_view_revenue must be null for all associated pixels
  • If profile_id is set, the associated profile may only target country, supply_type, device_type, operating_system_family, browser, device_model, or carrier

To set this field to false, performance_mkt_crossnet (in the valuation object) must also be false .

false
performance_mkt_managedboolean

If true, the line item is a performance marketplace line item that buys on managed inventory. This field is applicable only when revenue_type is "cpc" or "cpa".

false
performance_mkt_crossnetboolean

If true, the line item is a performance marketplace line item that buys on cross-net/third-party inventory. This field is applicable only when revenue_type is "cpc" or "cpa" and performance_offer is true .

To set this field to true, the following requirements must be met:

  • If revenue_type is "cpc", revenue_value must also be set.
  • payout_margin must be set
false
campaign_group_valuation_strategy enum

Alpha-Beta Notice

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


For line items with revenue_type “cpm”, “cpc” or “cpa”, determines which performance goal optimization strategy will be applied. Possible values are:
  • “prospecting” - To use AppNexus’ standard optimization.
  • "retargeting"- To optimize to a user retargeting segment. If you select this setting, you must also associate a user retargeting segment with the line item. To create user segments, see the Segment service. To associate user retargeting segments with the line item, see the Profile service.
null

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

heightintRead-only. The height of the creative.
stateenumRead-only. The state of the creative. Possible values: "active" or "inactive".
formatenumRead-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_auditedbooleanRead-only. If true, the creative is self-audited.
idintThe ID of the creative. Either id or code is required when updating creative association.
codestringThe custom code for the creative. Either id or code is required when updating creative association.

Budget Intervals

This array is only used for seamless line items.

Budget intervals on seamless line items must be copies of the budget intervals defined on their parent insertion orders. Budget intervals on the line item will automatically have the same start_date and end_date as their corresponding insertion order budget intervals but should have distinct budgets. These function as line item-specific "sub-budgets" of the budget on the corresponding insertion order budget interval.

Line item budget intervals are created (and linked to their insertion order budget intervals) by the parent_interval_id field. When creating a new seamless line item, you must populate the budget_intervals array with references to all budget intervals on all insertion orders you are associating with that line item (insertion orders are associated with line items via the insertion_orders array in the Line Item Service). This is done by adding objects to the array that contain a single field, parent_interval_id, whose value is an insertion order budget interval the line item should inherit. See Add a seamless line item with budget intervals in the Examples section below.

Also consider the following when using the budget_interval array:

  • Date ranges (e.g., start_date, end_date) of different budget intervals on the same line item cannot overlap.
  • Budget intervals on the line item can have unlimited lifetime budgets (i.e., if those budget fields are left set to null). 
  • Budget intervals cannot be used if budget fields on the top-most level of the insertion_order object itself are set.
  • Edits made to insertion order-level budget intervals are propagated to corresponding line item-level budget intervals (e.g., deleting a budget interval on the insertion order will also delete that budget interval on all line items that use it).
  • 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.

Each object in the budget_intervals array contains the following fields.

Field

Type (Length)

Description

id

int

The ID of the line item budget interval.
start_datetimestampThe start date of the budget interval, which is inherited from the insertion order. Format is YYYY-MM-DD hh:mm:ss.
end_datetimestampThe end date of the budget interval, which is inherited from the insertion order. Format must be YYYY-MM-DD hh:mm:ss (hh:mm:ss must be set to 23:59:59). Note that if the end_date of the parent insertion order's budget interval has been set to null (e.g, no end date), then the end_date on the line item must be set to a non-null value.
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.

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.

parent_interval_idintThe ID of the parent insertion order's budget interval. This is the id field in the budget_intervals array on the insertion order. Required in order for the line item's budget interval to inherit the values of the start_date and end_date fields in the insertion order's budget interval.
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. Set this field to 0 if you don't want the line item to spend during this budget interval.

This field defaults to null (unlimited).

lifetime_budget_impsint

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. Set this field to 0 if you don't want the line item to spend during this budget interval.

This field defaults to null (unlimited).

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

This field defaults to null (unlimited).

daily_budget_impsint

The daily budget in impressions.

This field defaults to null (unlimited).

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_targetdoubleThe post-click advertiser goal value for the pixel.
post_view_goal_targetdoubleThe post-view advertiser goal value for the pixel. (Comparable to goal_value for goal_type "cpc" and "ctr".)
post_click_goal_thresholddoubleThe post-click advertiser goal threshold for the pixel, which determines the bid/no bid cutoff on optimized campaigns. Cannot be enabled without a target set. (Comparable to goal_threshold in the valuation object for goal_type "cpc" and "ctr".)
post_view_goal_thresholddoubleThe post-view advertiser goal threshold for the pixel, which determines the bid/no bid cutoff on optimized campaigns. Cannot be enabled without a target set. (Comparable to goal_ threshold in the valuation object for goal_type "cpc" and "ctr".)

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.

At this time, there are no warnings for line items.

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.

128

All campaigns under this line item are inactive.

Flat Fee

The flat_fee object contains the following fields.

FieldTypeDescription
flat_fee_statusenumRead-only. The status of the flat fee disbursement. Possible values: "pending" , "processing" , "allocated" , or "error" .
flat_fee_allocation_datetimestampThe date when the flat fee revenue is scheduled to be allocated to publishers. Example: "2012-06-08 00:00:00"
This value will be null if the flat_fee_type is daily.
flat_fee_adjustment_idintThe ID for any adjustments required to this flat fee.

Roadblock

Roadblocks can be set at only one level, either line item or campaign. If a roadblock has been set on a campaign, it can't be set on the parent line item. Roadblocks can be applied only for managed inventory and can't be enabled when you're working with third-party inventory.

FieldTypeDescription
type
enum

The type of roadblock. Possible values include:

no_roadblock: There is no roadblocking set at the line item level.

normal_roadblock: The line item serves if the number of creatives is greater than or equal to the number of ad slots available.

partial_roadblock: The line item serves when at least one creative of each size fits an eligible ad slot.

exact_roadblock: The line item serves when the number of creatives is equal to the number of ad slots available.

master_width
intThe width of the master creative. Set this value only when using page-level roadblocking. For standard roadblocking, omit this field or set the value to 0. (Do not set the value to null.)
master_height
intThe height of the master creative. Set this value only when using page-level roadblocking. For standard roadblocking, omit this field or set the value to 0. (Do not set the value to null.)

The master creative is the creative with a size matching the master_height and master_width specified in the roadblock object. If more than one creative matches that size, the system will choose one as the master.

The master creative is used for page-level roadblocking, where one impression is recorded for the full set of creatives delivered for the roadblock. That recorded impression is based on the master creative. This means that if the master creative doesn't serve, no impression will be recorded. If you want to use creative-level roadblocking, where each creative delivered is counted as an impression, leave the master_width and master_height values blank.

For more on roadblocking, see Target Your Inventory with Roadblocking (customer login required).

Examples

Add a seamless line item with budget intervals
Add a non-seamless line item
Add a line item with a CPC performance goal
Add a line item with a CPA performance goal
Add a performance offer line item
View a line item
View all of an advertiser's line items

Modify a budget interval on a seamless line item

Related Topics