Line Item service - ALI

Note

This page describes the Line Item Service for augmented line items. It links to other API documentation that 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.

REST API

HTTP Method	Endpoint	Description
POST	https://api.appnexus.com/line-item?advertiser_id=ADVERTISER_ID (line item JSON)	Add a new line item.
PUT	- https://api.appnexus.com/line-item?id=LINEITEM_ID&advertiser_id=ADVERTISER_ID - https://api.appnexus.com/line-item?code=LINE-ITEM_CODE&advertiser_code=ADVERTISER_CODE (line item JSON)	Modify an existing line item.
GET	- https://api.appnexus.com/line-item?advertiser_id=ADVERTISER_ID - https://api.appnexus.com/line-item?code=LINE-ITEM_CODE&advertiser_code=ADVERTISER_CODE	View all of an advertiser's line items.
GET	https://api.appnexus.com/line-item?id=1,2,3 Note: 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 below.	View multiple line items by ID using a comma-separated list.
GET	https://api.appnexus.com/line-item?search=SEARCH_TERM	Search for line items with IDs or names containing certain characters.
DELETE	- https://api.appnexus.com/line-item?id=LINEITEM_ID&advertiser_id=ADVERTISER_ID - https://api.appnexus.com/line-item?code=LINE-ITEM_CODE&advertiser_code=ADVERTISER_CODE Warning: Deletion is Recursive and Permanent Deleting a line item will also delete all of its impression trackers, click trackers, associated budget intervals, and splits. 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).	Delete a line item.

Note

About Performance Goals

Goal Pixels 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 of objects and the Valuation object below. 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. For more details on which fields to set, see the description of the valuation object below.

About Geography Targeting

For Augmented Line Item, it is mandatory to set at least one country as geography targeting. To add geography targeting, see Country Targets under Targeting section in the Profile Service page.

JSON fields

General

Field	Type	Description
id	int	The ID of the line item. Required On: 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. Default: null
name	string (255)	The name of the line item. Required On: 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". Default: "active"
line_item_type	enum	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). - "curated": Curated line item. Note: Ensure this field is set to "standard_v2" for ALIs. Default: "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. Default: 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. Default: null (indefinitely)
timezone	enum	The timezone by which budget and spend are counted. For details and accepted values, see API Timezones. 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. Default: "UTC" or advertiser's timezone.
ad_types	array of strings	The type of creative used for this line item. Possible values: - "banner" - "video" - "native" - "audio" 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. Note: All creatives associated to a line item must have the same ad type, which should match the ad_types selected here. Default: "banner" Required On: POST/PUT
discrepancy_pct	double	Deprecated.
publishers_allowed	string	Deprecated. Use the values of the supply_strategies array to set the supply types (e.g., RTB/Open Exchange, Deals, Managed).
revenue_value	double	The amount paid to the network by the advertiser. Note: 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%). Required On: 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 the Xandr viewability measurement, using the IAB definition.   - If CPCV, set this to "cpm", the ad_types field to "video", "revenue_auction_event_type" to "video", "revenue_auction_event_type_code" to "video_completion", and "revenue_auction_type_id" to 10. - "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. Note: If programmatic_guaranteed (in supply_strategies) is set to true, revenue_type must be set to cost_plus_margin or cost_plus_cpm. - "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 a percentage 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). - "cost_plus_cpm": Media cost (what you spend on inventory) plus a service fee that you charge the advertiser based on CPM revenue. If selected, you must also set the revenue_value to a flat CPM margin you receive (e.g., 1 for a $1 CPM). 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). Note: 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". Default: "none"
goal_type	enum	For line items that make use of performance goals. Possible values: null, "cpc", "cpa", "ctr", or "custom". - If you want to optimize to a CPA performance goal for both post-click and post-view conversions, set this field to "cpa". You must also set the post_click_goal_threshold and post_videw_goal_threshold fields (in the goal_pixels array of objects) to your CPA goal. These values must be the same, since Xandr will optimize to one value. Additionally, you must set campaign_group_valuation_strategy to "retargeting" or "prospecting". For details, see campaign_valuation_strategy in Valuation below. - If you want to optimize to a CPA performance goal for only post-click conversions, set this field to "cpa". You must also set the post_click_goal_target and post_click_goal_threshold fields (in the goal_pixels array of objects) to your CPA goal. - If you want to optimize to a CPC 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_pixel 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 optimize to a CTR goal, set this field to "ctr". In addition, you must also set the goal_target and the goal_threshold in the valuation object to the desired clickthrough rate (a decimal value between 0 and 1). - 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". For details, see Custom Models. - 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 Default: "none"
goal_value	double	Deprecated. Use valuation object instead. For details, see Valuation below.
last_modified	timestamp	The time of last modification to this line item. Read Only.
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. Note: Once the line item has been created, the currency cannot be changed. Tip: As a best practice, align currency to the billing currency in order to achieve the best possible local currency experience. Default: Default currency of the advertiser.
require_cookie_for_tracking	boolean	Indicates whether you want to serve only to identified users for conversion-tracking purposes. If set to true, you won't serve to anonymous users because they have a lower potential for conversion attribution. If set to false, this indicates that you'll serve to anonymous users and accept only IP-based conversion attribution for those users (if turned on). This field's setting is only relevant when a conversion pixel has been applied, so setting this to true won't require identifiers for a line item that has no conversion pixels. - If true, an identifier is required for conversion tracking. - If programmatic_guaranteed (in supply_strategies) is set to true, require_cookie_for_tracking must be set to false. Default: true
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. For details, see the Profile Service.
member_id	int	ID of the member that owns the line item.
comments	string	Comments about the line item.
remaining_days	int	The number of days between today and the end_date for the line item. Note: This will be null if the start_date is in the future or if either the start_date or end_date is not set. Read Only.
total_days	int	The number of days between the start_date and end_date for the line item. Note: This will be null if either the start_date or end_date is not set. Read Only.
advertiser	object	An object describing the advertiser with which this line item is associated. For details, see Advertiser below. Read Only.
labels	array	The optional labels applied to the line item. Currently, the labels available are: "Trafficker" and "Sales Rep". For more details, see Labels below. Note: 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	Deprecated. Use partner_fees instead.
pixels	array of objects	The conversion pixels used to track CPA revenue. 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, speak with your Xandr Implementation Consultant or Support. For more details, see Pixels and the example below for a sample of the format. Default: null
broker_fees	array	Deprecated. Use partner_fees instead.
pixels	array of objects	The conversion pixels used to track CPA revenue. 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, speak with your Xandr Implementation Consultant or Support. For more details, see Pixels and the example below for a sample of the format. Default: 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. Note: Once a line item is associated with a seamless insertion order, it cannot be associated to a legacy insertion order.
goal_pixels	array of objects	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. For more details, see Goal Pixels and the example below for a sample of the format.
imptrackers	array of objects	The third-party impression trackers associated with the line item. For more details, see Impression Tracker Service. Read Only.
clicktrackers	array of objects	The third-party click trackers associated with the line item. For more details, see Click Tracker Service. Read Only.
valuation	object	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 of objects). For more details, see Valuation below.
creatives	array of objects	The creatives that are associated with the line item. For more details, see Creatives below.
budget_intervals	array of objects	Budget intervals enable multiple date intervals to be attached to a line item, each with corresponding budget values. For more details, see Budget Intervals below. Note: 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 - subflights
lifetime_budget	double	Do not use this field. Instead, use the budget fields within the budget_intervals array. Default: null (unlimited)
lifetime_budget_imps	int	Do not use this field. Instead, use the budget fields within the budget_intervals array. Default: null (unlimited)
daily_budget	double	Do not use this field. Instead, use the budget fields within the budget_intervals array. Default: null (unlimited)
daily_budget_imps	double	Do not use this field. Instead, use the budget fields within the budget_intervals array. Default: 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. Default: 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. Default: null
lifetime_pacing_span	int	Note: Do not use or edit the value of this field. Default: null (3 days)
lifetime_pacing_pct	double	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. Default: 100
payout_margin	double	The payout margin on performance offer line items.
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. For details, see the Insertion Order Service.
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	To show 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. Read Only.
first_run	timestamp	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. Read Only.
last_run	timestamp	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. Read Only.
expected_pacing	double	Deprecated. Note: The stats object and Quickstats have been deprecated (as of October 17, 2016).
total_pacing	double	Deprecated. Note: The stats and Quickstats have been deprecated (as of October 17, 2016).
has_pacing_dollars	enum	Deprecated. Note: The stats object and Quickstats have been deprecated (as of October 17, 2016).
has_pacing_imps	enum	Deprecated. Note: The stats object and Quickstats have been deprecated (as of October 17, 2016).
imps_pacing_percent	int	Deprecated. Note: The stats object and Quickstats have been deprecated (as of October 17, 2016).
rev_pacing_percent	int	Deprecated. Note: The stats object and Quickstats have been deprecated (as of October 17, 2016).
alerts	object	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. Read Only.
inventory_type	enum	Deprecated. 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 Ad Manager). "Direct" includes only inventory managed by your network. Note: 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. Default: "real_time"
supply_strategies	object	An 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_type	enum	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 automatically by our system. Also select this if you want creative rotation to be handled at the splits level. - 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. Default: null Note: If a specific creative_distribution_type is not passed through the API (null value is passed), then value of creative_distribution_type is set to even.
prefer_delivery_over_performance	boolean	This field is used to indicate your goal priority (whether you wish to give greater priority to delivery, performance, or margin). Options are: - true: This option (delivery) prioritizes impression volume by multiplying bids up to 2x in response to delivery. When you optimize to clicks, it also allows line items to discover inventory with historical CPCs up to 10x the goal. Warning: This may cause margin and performance to be deprioritized, possibly resulting in a negative margin. - false: Select this option to do one of the following:   - Prioritize performance (e.g., clicks). This prioritizes your advertiser goal over impression volume and profit. If you select this option, you must also set min_margin_pct (in the valuation object) to null.   - Prioritize margin. This reduces optimized bids by your desired profit margin. Additional margin may be earned through Adaptive Pacing if your revenue type is CPM, Dynamic CPM, Viewable CPM, or CPC. 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%) Default: false
use_ip_tracking	boolean	Determines whether IP Attribution is enabled or not for a given line item.
viewability_vendor	string	This field determines what provider measures the viewability of the ad unit. The only value that is currently valid is "appnexus". Default: "appnexus"
is_archived	boolean	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. Note: 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. Default: false
archived_on	timestamp	The date and time on which the line item was archived (i.e., when the is_archived field was set to true). Default: null Read Only.
partner_fees	Array	An array of partner fees applied to this line item. You can create or view third-party partner fees with the Partner Fee Service. For more details, see Partner Fees below.
line_item_subtype	enum	The subtype of the line item. The line_item_subtype field cannot be changed after the line item is created. For Invest buyers, the supported values are as follows: - standard_buying: Augmented line item eligible to serve on managed, RTB, or deals. Omitting the line_item_subtype on POST requests will default to this subtype behaviour. - pg_buying: Eligible only to transact on PG deals. If the subtype is passed on the POST, the line_item_type, bid_object_type, delivery_model_type, and supply_strategies fields are not required. - standard_curated: For curated deal line items. For more details, see line_item_subtype in Curated Deal Line Item API Setup Guide. Default: standard_buying

Budgeting/pricing

Field	Type	Description
lifetime_budget	double	The lifetime budget in dollars (media cost). Null corresponds to "unlimited". Warning: 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. Default: null
lifetime_budget_imps	int	The lifetime budget in impressions. Null corresponds to "unlimited". Default: null
daily_budget	double	The daily budget in dollars (revenue). Null corresponds to "unlimited". Default: null
daily_budget_imps	int	The daily budget in impressions. Null corresponds to "unlimited". Default: null
learn_budget	double	Deprecated. Default: null
learn_budget_imps	int	Deprecated. Default: null
learn_budget_daily_cap	double	Deprecated. Default: null
learn_budget_daily_imps	int	Deprecated. Default: 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. Default: 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. Default: 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. Default: 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. Default: 5
expected_pacing	double	Deprecated. Note: The stats object and Quickstats have been deprecated (as of October 17, 2016).
total_pacing	double	Deprecated. Note: The stats object and Quickstats have been deprecated (as of October 17, 2016).
has_pacing_dollars	enum	Deprecated. Note: The stats object and Quickstats have been deprecated (as of October 17, 2016).
has_pacing_imps	enum	Deprecated. Note: The stats object and Quickstats have been deprecated (as of October 17, 2016).
imps_pacing_percent	int	Deprecated. Note: The stats object and Quickstats have been deprecated (as of October 17, 2016).
media_cost_pacing_percent	int	Deprecated. Note: 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. You can target any combination of the rtb (Open Exchange), managed, or deals fields by setting each to true or false. If you are targeting a programmatic guaranteed deal, set the programmatic_guaranteed field to true and the rtb, managed, and deals fields to false. At least one of these supply_strategies object fields must be set to true.

Note

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.

Warning

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

Note

The Line Item API Service supports Roadblocks only if the supply_strategy is managed.

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 Ad Manager).
managed	boolean	Designates whether you wish to target managed inventory. This only includes inventory managed by your network.
deals	boolean	Designates whether you wish to target deal inventory. This includes any deals which you are are eligible to bid on.
programmatic_guaranteed	boolean	Designates whether you wish to target a programmatic guaranteed deal with this line item. If this is set to true, then the rtb, managed, and deals fields must be set to false.

Target open exchange and 2 deals but not managed inventory

{code} $ cat LI-supply-strategies.json

{
    "line-item": {
      ...
      "supply_strategies": {
          "managed": false,
          "rtb": true,
          "deals": true
      }
      ...
    }
}
 
$ cat profile-supply-strategies.json 
{
    "profile": {
      "deal_action_include": true,
      "deal_targets": [
          {
              "id": 44,
              "name": "Deal with external supply partner",
              "code": "APN-1234-2200f"
          },
          {
              "id": 45,
              "name": "Deal with Console seller",
              "code": null
          }
      ]
  }
}
{code}

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

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

Partner fees

If you need to reserve a portion of your budget for third-party costs—costs owed to parties other than the publisher—you can define this information with the Partner Fee Service. Fees can be tracked on a CPM, cost share, or revenue share basis, and can be applied to multiple advertisers and line items, if desired. A single advertiser or line item can have multiple fees applied.

The partner fee array includes the following field:

Field	Type	Description
id	int	The ID of a partner fee applied to this line item.

Apply a fee to a line item

$cat LI-update.json

{
    "line-item": {
        "partner_fees": [
            {"id": 4401
            },
            { "id": 4402
            }
    ]
}

$curl -b cookie -X PUT -d @LI-update.json "https://api.appnexus.com/line-item?id=2345432"

{
    "response": {
        "status" : "OK",
        "id": 2345432
    }
}

Remove a fee from a line item

Note

You cannot remove a fee from a line item if required on the partner fee is true. You must first set required to false and then remove the fee from the line item.

$curl -b cookie -x GET "https://api.appnexus.com/line-item?id=2345432"

 {
    "line-item": {
        ...,
        "partner_fees": [
            {
                "id": 1
            },
            {"id": 2
            }, 
            {"id": 3
            }
        ],
        ...
    }
}

$cat LI-update.json

{
    "line-item": {
        "partner_fees": [
            {
                "id": 1
            },
            {
                "id": 3
            }, 
    ]
                }
}

$curl -b cookie -X PUT -d @LI-update.json "https://api.appnexus.com/line-item?id=2345432"

{
    "line-item": {
        ...,
        "partner_fees": [
            {
                "id": 1
            },
            {
                "id": 3
            }
        ],
        ...
    }
}

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. This field can only be set when the line item's revenue_type field has been set to cpa (as a result, this field can't be used with augmented line items).
post_view_revenue	double	The post view revenue value for the pixel. This field cab only be set when the line item's revenue_type field has been set to cpa (as a result, this field can't be used with augmented line items).
name	string	The name of the conversion pixel. Read Only.
trigger_type	enum	The type of event required for an attributed conversion. Possible values: "view", "click", or "hybrid". Read Only.

Insertion orders

Field	Type	Description
id	int	The unique ID of the insertion order. Note: 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. For a list of allowed values, see API Timezones.
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. Note: For best results, set the currency on the parent insertion order. For more information, see Insertion Order Service.
budget_intervals	array 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. For more information, see Insertion Order Service.

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
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. Default: 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 a CTR or CPC goal, or a CPA goal for only post-click conversions. - If you are optimizing to a CTR, enter the desired clickthrough rate (a value between 0 and 1). If you are optimizing to a CPC goal, enter your CPC goal. - If you are optimizing to a CPA goal for only post-click conversions, enter your CPC goal (not your CPA goal), and set the post_click_goal_task and post_click_goal_threshold fields in the goal_pixels array of objects. Note: - If you are optimizing to a CPA goal with both post-click and post-view conversions, see Goal Pixels below for required settings. Default: null
goal_target	decimal	The performance goal target is a required value when you are optimizing to a CTR, CPC goal, CPA goal (for only post-click conversions), or Viewable CPM goal. - If you are optimizing to a CTR, enter the desired clickthrough rate (a value between 0 and 1). - If you are optimizing to a CPC goal, enter your CPC goal. - If you are optimizing to a CPA goal for only post-click conversions, enter your CPC goal (not your CPA goal), and set the post_click_goal_target and post_click_goal_threshold fields in the goal_pixels array of objects. - If you are optimizing to a Viewable CPM, set this field to null.
campaign_group_valuation_strategy	enum	Determines whether a line item that has a CPA goal for both post-click and post-view conversions is optimized for retargeting or prospecting. - Set to "retargeting" for a retargeting line item (a line item that aims to drive users who have already shown interest in the brand further down a conversion funnel). The line item profile must target at least one segment that is not in the data marketplace. Use the Profile Service to set up segment targeting. - Set to "prospecting" for a prospecting line item (a line item that aims to drive new users into a conversion funnel).
min_avg_cpm	double	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_cpm	double	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.
min_margin_cpm	double	Margin Value when Margin Type is CPM. Note: The min_margin_cpm and min_margin_pct fields cannot both be set at the same time. If one is set, the other must be null. Xandr validates customer entitlements when clients use these fields. Default: null
min_margin_pct	double	Margin Value when Margin Type is Percentage. Note: The min_margin_cpm and min_margin_pct fields cannot both be set at the same time. If one is set, the other must be null. Xandr validates customer entitlements when clients use these fields. Default: null

Auction event

The following fields are contained within the auction_event object.

Note

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.

Field	Type	Description
revenue_auction_event_type	string	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 the Xandr viewability measurement, using the IAB definition. - "click": Use this value when your Revenue Type is CPC. - "video": Use this value when your Revenue Type is CPCV.
revenue_auction_event_type_code	string	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. - "video_completion": Use this value when your Revenue Type is CPCV.
revenue_auction_type_id	int	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. - 10: Use this value when your Revenue Type is CPCV.
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 optimizing to CPC, CPA, CTR, 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. - "video": Use this value when you are optimizing to CPCV or VCR.
kpi_auction_event_type_code	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 optimizing to CPC, CPA, CTR, or not using optimization. - "view_display_50pv1s_an": Use this value when you are optimizing to a Viewable CPM. - "video_completion": Use this value when you are optimizing to CPCV or VCR.
kpi_auction_type_id	int	This field is used in conjunction with the settings of the goal_type field. Options are: - 1: Use this value when you are optimizing to CPC, CPA , CTR, or not using optimization. - 2: Use this value when you are optimizing to a Viewable CPM. - 10: Use this value when your Revenue Type is CPCV or VCR.
kpi_value	double	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 optimizing to CPC, CPA, CTR, or not using optimization. - your goal: If you are optimizing to Viewable CPM goal (e.g., 5)., CPCV or VCR. VCR goals must be between 0 and 1.
kpi_value_type	string	This field is used in conjunction with the settings of the kpi_code field. Set this to one of the following: - none: If you are optimizing to CPC, CPA, CTR, or not using optimization. - goal_value: If you are optimizing to a cost-based goal not covered above (CPCV). - rate_threshold: If you are optimizing to a rate-based goal not covered above (VCR).
payment_auction_event_type	string	This field is only relevant if you have either set inventory_type to "real_time" (RTB) or set the rtb field in the supply_strategies object to true. 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. - "video": If you want to pay per video complete.
payment_auction_event_type_code	string	This field is only relevant if you have either set inventory_type to "real_time" (RTB) or set the rtb field in the supply_strategies object to true. 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). - "video_completion": If you want to pay per video complete.
payment_auction_type_id	int	This field is only relevant if you have either set inventory_type to "real_time" (RTB) or set the rtb field in the supply_strategies object to true. 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). - 10: If you want to pay per video complete.

Budget scheduling settings

The following fields are contained within the budget_scheduling_settings object.

Field	Type (Length)	Description
underspend_catchup_type	enum	Dictates how Xandr's system deals with an underdelivered daily budget. Use the "evenly" value if you'd like the unspent portions of your budget to be spent evenly throughout the rest of flight, or "ASAP" if you'd like the unspent budget to be spent as soon as possible. Possible values: "evenly" or "ASAP".

Demographic measuring

The in_demo_measurement object enables demographic measuring and its relevant specifications for your line item. The in_demo_measurement object is a part of the Nielsen Digital Ad Ratings (DAR) feature, which costs $0.25 CPM to use.

Note

To utilize demographic measuring for connected TV (CTV), your line item must have a targeting configuration that exclusively targets within the United States.

An example of the in_demo_measurement object within a JSON response

"in_demo_measurement": {
    "campaign_group_id": 12795878,
    "provider": "nielsen-dar",
    "status": "active",
    "pixel": null,
    "attributes": [{
            "key": "on_target_goal_pct",
            "value": "50"
        },
        {
            "key": "target_gender",
            "value": "all"
        },
        {
            "key": "target_age_lower",
            "value": "13"
        },
        {
            "key": "target_age_upper",
            "value": "99"
        }
    ]
},
...

Field	Type (Length)	Description
campaign_group_id	int	This field is used to associate the in_demo_measurement object with this line item. This field's value is your line item's ID. Read Only.
provider	string	This field indicates which third-party provider is providing the demographic measuring service. Currently, the only possible value for this field is "nielsen-dar". Required.
status	boolean	This field indicates whether or not the selected provider has acknowledged and begun demographic measuring for your line item. To activate demographic measurement, set this field to "active". It can take up to 24 hours for a third-party measurement provider to begin tracking your line item's impressions, during which time this field's value is set to "active-pending". Possible values: - "active": Measurement has been activated for this line item, and Xandr has received an acknowledgment from a third-party measurement provider's API. Impressions are being measured. - "active-pending": Measurement has been activated for this line item, but impressions aren't being measured as the line item awaits confirmation from a third-party measurement provider’s API. - "inactive": Measurement isn't currently enabled for this line item. - "inactive-pending": This value is similar to "inactive", but it indicates that your selected third-party measurement provider's API hasn't yet processed your line item's deactivation request. Once the third-party measurement provider has acknowledged your line item's measurement deactivation, this value changes to "inactive". Required.
pixel	array of objects	The default value for this field is null. Read Only.
attributes	array of objects	The attributes array of objects is comprised of four key-value objects containing values to specify what demography your line item is measuring its targeting performance against. For more information on the attributes array of key-value objects, see the Demographic Attributes table below. Required.

attributes objects

"attributes":[
{
"key":"on_target_goal_pct",
"value":"50"
},
{
"key":"target_gender",
"value":"all"
},
{
"key":"target_age_lower",
"value":"13"
},
{
"key":"target_age_upper",
"value":"99"
}
]

Demographic attributes

Key	Type (Length)	Description
on_target_goal_pct	double	Indicates how often you'd like your line item to deliver to your specified demography (such specification is done by inserting values for the keys below). This reference goal percentage is used in reporting and doesn't affect line item performance. Possible values: 1 to 100.
target_gender	string	Specifies the gender of the demography that you're trying to target. Possible values: "all", "male", or "female".
target_age_lower	int	Specifies the age threshold of the demographic age range that you're trying to target. Possible values: 13, 18, 21, 25, 30, 35, 40, 45, 50, 55, 60, or 65.
target_age_upper	int	Specifies the age limit for the demographic age range that you're trying to target. Possible values: 17, 20, 24, 29, 34, 39, 44, 49, 54, 59, 64, or 99 (which represents ages 65+).

Offline attribution

The offline_attribution object enables offline sales attribution for your line item. Offline sales attribution is a Beta feature provided by Nielsen Catalina Solutions (NCS), so you'll need to gain Beta testing access to this feature prior to using it. To gain access, contact your Xandr account representative.

Note

To utilize offline sales attribution, your line item must have a targeting configuration that exclusively targets within the United States.

An example of the offline_attribution object within a JSON PUT request

$ cat line-item.json

{
    "line-item": {
        "id": 1,
        ...
        "offline_attribution": {
            "product_group_id": 123,
            "report_level_type": "line_item",
            "frequency_type": "weekly",
            "lookback_type": "flight_lifetime"
        }
    }
}

$ curl -b cookies -c cookies -X PUT -d @line-item.json "https://api.appnexus.com/line-item?id=ID_INTEGER&advertiser_id=ID_INTEGER"

An example of the offline_attribution object within a JSON response

{
    "line-item": {
        "id": 1,
        ...
        "offline_attribution": {
            "product_group_id": 123,
            "product_group": {
                "provider_member_name": "ncs",
                "category_name": "CATEGORY NAME",
                "brand_name": "BRAND NAME",
                "product_high_name": "PRODUCT HIGH NAME",
                "product_low_name": "PRODUCT LOW NAME",
            }
            "report_level_type": "line_item",
            "frequency_type": "weekly",
            "lookback_type": "flight_lifetime"
        }
    }
}
...

An example of the offline_attribution object being deleted within a JSON PUT request

$ cat line-item.json

{
    "line-item": {
        "id": 1,
        ...
        "offline_attribution": null
    }
}

$ curl -b cookies -c cookies -X PUT -d @line-item.json "https://api.appnexus.com/line-item?id=ID_INTEGER&advertiser_id=ID_INTEGER"

Field	Type	Description
product_group_id	int	The product group entry to report on. You can find a product group ID by using the Offline Attribution Product Group Service. Required.
offline_attribution_product_group	object	An object that returns information on the product group you're tracking against (based on your product_group_id selection) such as its - provider_member_name - category_name - brand_name - product_high_name - product_low_name Read Only.
report_level_type	string	What you want to show sales attribution data for in your generated reports. Potential values: - "line_item" - "split" Required.
frequency_type	string	Pertains to when you'll start receiving offline sales attribution data reports for your line item and how often new reports will be made. Potential values: - "weekly" - "per_flight" Required.
lookback_type	string	Pertains to how much line item data is shown in each generated report (this field is also based on your frequency_type selection). Potential values: - "flight_lifetime" - "last_week" Required.

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	If true, the creative is expired. If false, the creative is active. Read Only.
is_prohibited	boolean	If true, the creative falls into a prohibited category on the Xandr platform. Read Only.
width	int	The width of the creative. Read Only.
audit_status	enum	The audit status of the creative. Possible values: "no_audit", "pending", "rejected", "audited", or "unauditable". Read Only.
name	string	The name of the creative. Read Only.
pop_window_maximize	boolean	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. Read Only.
height	int	The height of the creative. Read Only.
state	enum	The state of the creative. Possible values: "active" or "inactive". Read Only.
format	enum	The format of the creative file. Possible values: "url-html", "url-js", "flash", "image", "raw-js", "raw-html", "iframe-html", or "text". Read Only.
is_self_audited	boolean	If true, the creative is self-audited. Read Only.
id	int	The ID of the creative. Either id or code is required when updating creative association.
code	string	The custom code for the creative. Either id or code is required when updating creative association.
weight	int	A 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.
ad_type	string	The creative ad type. Possible values: "banner", "video", "native", "audio". Note: All creatives associated to a line item must have the same ad type, which should match the ad_types selected for the line item. Read Only.
all_budget_intervals	boolean	Indicates whether the creative will serve during all budget intervals, including all future budget intervals. Possible values are: - True (the default) - False If true, custom_date_ranges in the creatives array and creatives in the budget_intervals array must be set to null. Conversely, if you want to use custom date ranges and/or creatives, all_budget_intervals must be set to false.
custom_date_ranges	array of objects	The date ranges setting the periods when the creative will serve. If specified: all_budget_intervals must be set to false. For more information, see Custom Date Ranges below.

Custom date ranges

The custom_date_ranges array sets the date ranges during which a creative will serve.

Dates must be in the format YYYY-MM-DD hh:mm:ss.

The date ranges must all meet the following specifications:

• They cannot include any dates before the start or after the end of any budget intervals defined for this line item.
• Date ranges must be at least an hour long.
• End dates cannot be later than 2038-01-19 00:00:00.

Field	Type (Length)	Description
start_date	timestamp	The start date of the custom date range. Format must be YYYY-MM-DD hh:mm:ss (hh:mm:ss should be hh:00:00).
end_date	timestamp	The 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).

Schedule a creative to serve during a custom budget interval

$cat line-item-with-custom-budget-intervals
{
    line_item: {
        budget_intervals: [
            {
                start_date: 1/1/2020,
                end_date: 2/1/2020,
                lifetime_budget: 1000,
                id: 7777,                                  
                creatives: [12345]                          
            },
            {
                start_date: 2/1/2020,
                end_date: 3/1/2020,
                lifetime_budget: 2000,
                id: 8888,                                  
                creatives: null
            }
        ],
        creatives: [
            {
                id: 12345,
                weight: 1,
                all_budget_intervals: false,                
                custom_date_ranges: [
                    {                                      
                        start_date: 2/5/2020 00:00:00,      
                        end_date: 2/10/2020 00:00:00                     
                    }
                ]
            },
            {
                id: 56789,
                weight: 2,
                all_budget_intervals: true,                 
                custom_date_ranges: null                                                   
            }
        ],
        creative_distribution_type: weighted
    }
}

Budget intervals

Budget intervals on an augmented line item must fall within the budget intervals defined on the line item's 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).

Note

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.

Note

• 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_date	timestamp	The start date of the budget interval. Format must be YYYY-MM-DD hh:mm:ss (hh:mm:ss should be hh:00:00).
end_date	timestamp	The 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.
timezone	string	The timezone by which budget and spend are counted. For a list of acceptable timezone values, see API Timezones.
parent_interval_id	int	Deprecated. 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_budget	double	The lifetime budget in revenue for the budget interval. The revenue currency is defined by the currency field on the insertion_order object. Note: 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_imps	double	The lifetime budget in impressions for the budget interval. Note: If you add line items to this insertion order, any spend already associated with those line items before they are added to the insertion order is NOT counted against the lifetime budget of the insertion order. Only spend that occurs while the line item is a child of the insertion order is counted. Note: 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_pacing	boolean	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_budget	double	The daily budget in revenue for the budget interval. The revenue currency is defined by the currency field on the insertion_order object. Note: If you add line items to this insertion order, any impressions associated to those line items when they are added to the insertion order are NOT counted under the lifetime budget of the insertion order. Only impressions that occur while the line item is a child of the insertion order are counted. Note: 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_imps	double	The daily budget in impressions. Note: 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_pacing	boolean	If true, then spending will be paced over the course of the day. Only applicable if there is a daily_budget.
creatives	array	Specifies the creatives associated with this budget interval. In order to serve, creatives must also be specified in the line item creatives field and all_budget_intervals must be false.

Delete a budget interval

Note

You may remove budget intervals from an augmented line item. However, if you want to remove a budget interval from the parent insertion order, you must first remove any budget intervals (that fall within the parent insertion order's budget interval) from all augmented line items associated with the insertion order. Only then can you remove the budget interval from the insertion order. For more details, see Insertion Order Service.

$ cat delete-budget-interval
{
  "line-item": {
    "budget_intervals": [
      {
        "id": 79970,
        "start_date": null,
        "end_date": null
      }
    ]
  }
}

Create a subflight

$ cat create-subflight

{
  "line-item": {
    ...,
    "budget_intervals": [
      {
        "id": 342856,
        "lifetime_pacing_percent": 150,
        "lifetime_budget": 10000,
        "lifetime_budget_imps": null,
        "start_date": "2022-04-01 00:00:00",
        "end_date": "2022-04-30 11:59:59",
        ...,
        "subflights": [
          {
            "id": 1, // ID generated on LI creation or update
            "name": "spend 200 every weekend for entire flight",
            "is_recurring": true,
            "use_flight_date_range": true,
            "recurring_day_of_week": [0,1,6],
            "start_date": null,
            "end_date": null,
            "daily_budget": 80,
            "daily_budget_imps": null,
            "subflight_pacing_percent": null,
          }
        ]
      }
    ],
    ...
  }
}

Delete a subflight

$ cat delete-subflight

{
  "line-item": {
    ...,
    "budget_intervals": [
      {
        "id": 342856,
        "subflights": [
          {
            "id": 1,
            "use_flight_date_range": false,
            "start_date": null,
            "end_date": null,
          }
        ]
      }
    ],
    ...
  }
}

Field	Type (Length)	Description
id	int	The subflight ID generated upon creating a new subflight. Read Only.
name	string	The name given to the subflight. Required.
is_recurring	boolean	Determines if the subflight is to be recurring. Having a recurring subflight means that you can select certain days of the week for which your subflight will take effect, whereas a standard subflight operates constantly under its start and end dates. Possible Values: - true: Recurring subflight. - false: (default value) Standard subflight. Required.
recurring_day_of_week	array of integers	Determines which days of the week your recurring subflight will take effect. Select either a single day or up to six consecutive days. Possible Values: - 0 (Sunday) - 1 (Monday) - 2 (Tuesday) - 3 (Wednesday) - 4 (Thursday) - 5 (Friday) - 6 (Saturday) Saturday-Monday Example: "recurring_day_of_week": [0, 1, 6]. Required if is_recurring equals true.
use_flight_date_range	boolean	Determines whether the subflight uses its parent flight’s date range or its own date range, as determined by the subflight’s start_date and end_date selections. Possible Values: - true: The subflight will use its parent flight’s date range. - false: The subflight will use its own start and end date. Note: If you set is_recurring to false, then you must also set use_flight_date_range to false. Required.
start_date	date (yyyy-mm-dd)	The subflight’s start date (relative to your line item’s designated time zone). Your start date selection must match or start later than the start date selected for the subflight’s budget interval. Note: If use_flight_date_range is set to true, this field's value must be set to null. Required if is_recurring equals false.
end_date	date (yyyy-mm-dd)	The subflight’s end date (relative to your line item’s designated time zone). Your end date selection must match or end earlier than the end date selected for the subflight’s budget interval. Note: If use_flight_date_range is set to true, this field's value must be set to null . Required if is_recurring equals false.
daily_budget	int	Determines how much money you want your subflight to be able to spend daily. To make a selection for this field, you must set the parent flight’s lifetime_pacing_percent field selection to null. Note: If your line item is underspending while utilizing subflights with daily budgets, underspend catch-up settings will take effect on the next non-subflight date. Required if daily_budget isn't provided for the parent flight.
daily_budget_imps	double	The daily number of impressions that the subflight is allowed to win. Note: If your line item is underspending while utilizing subflights with daily budgets, underspend catch-up settings will take effect on the next non-subflight date. Required if: - The parent flight's daily_budget equals true and the subflight's daily_budget equals null. - The parent flight's lifetime_pacing_percent equals null.
subflight_pacing_percent	double	Determines how evenly the subflight's budget is distributed between its start and end date. If set to 100, the subflight's budget pacing is unaltered and distributed over every applicable day for the subflight, with roughly similar budget amounts being spent daily. If set higher than 100, the subflight spends more per day at the beginning of its date range and less at the end. The reverse occurs if the pacing is lower than 100. Possible Values: 50-150 Required if daily_budget isn't provided.

Goal pixels

The goal_pixels array of objects is used when working with goal_type "cpa" and contains information about performance goal targets and thresholds. Each object in the goal_pixels array of objects 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	The type of event required for an attributed conversion. Possible values: "view", "click", or "hybrid". Read Only.
post_click_goal_target	double	The advertiser goal value for post-click conversions for the pixel. If you want to set a CPA goal and optimize to only post-click conversions, set this field to your CPA goal value.
post_view_goal_target	double	The advertiser goal value for post-view conversions for the pixel (comparable to goal_value for goal_type "cpc"). If you want to set a CPA goal and optimize only to post-view conversions, ensure this field is set to null.
post_click_goal_threshold	double	The advertiser goal threshold for post-click conversions for the pixel. This determines the bid/no bid cutoff on optimized line items. If you want to set a CPA goal and optimize to both post-click and post-view conversions, this field must contain the same value as post_view_goal_threshold.
post_view_goal_threshold	double	The advertiser goal threshold for post-view conversions for the pixel. This determines the bid/no bid cutoff on optimized line items. If you want to set a CPA goal and optimize to both post-click and post-view conversions, this field must contain the same value as post_click_goal_threshold.

Stats

Note

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

Pass never_run=true in the query string.

curl -b cookies -c cookies 'https://api.appnexus.com/line-item?advertiser_id=100&flight_info=true&never_run=true'

Note

You can use never_run=true in combination with other filters, but note that it will always be an OR relationship. For example, if you pass both never_run=true and min_first_run=2012-01-01 00:00:00 in the query string, you will be looking for line items that have never served OR line items that first served on or after 2012-01-01.

Retrieve only line items that first served on or after a specific date

Pass min_first_run=YYYY-MM-DD HH:MM:SS in the query string.

curl -b cookies -c cookies 'https://api.appnexus.com/line-item?advertiser_id=100&flight_info=true&min_first_run=2012-01-01 00:00:00'

Retrieve only line items that first served on or before a specific date

Pass max_first_run=YYYY-MM-DD HH:MM:SS in the query string.

curl -b cookies -c cookies 'https://api.appnexus.com/line-item?advertiser_id=100&flight_info=true&max_first_run=2012-08-01 00:00:00'

Retrieve only line items that first served within a specific date range

Pass min_first_run=YYYY-MM-DD HH:MM:SS&max_first_run=YYYY-MM-DD HH:MM:SS in the query string.

curl -b cookies -c cookies 'https://api.appnexus.com/line-item?advertiser_id=100&flight_info=true&min_first_run=2012-01-01 00:00:00&max_first_run=2012-08-01 00:00:00'

Retrieve only line items that last served on or after a specific date

Pass min_last_run=YYYY-MM-DD HH:MM:SS in the query string.

curl -b cookies -c cookies 'https://api.appnexus.com/line-item?advertiser_id=100&flight_info=true&min_last_run=2012-01-01 00:00:00'

Retrieve only line items that last served on or before a specific date

Pass max_last_run=YYYY-MM-DD HH:MM:SS in the query string.

curl -b cookies -c cookies 'https://api.appnexus.com/line-item?advertiser_id=100&flight_info=true&max_last_run=2012-08-01 00:00:00'

Retrieve only line items that last served within a specific date range

Pass min_last_run=YYYY-MM-DD HH:MM:SS&max_last_run=YYYY-MM-DD HH:MM:SS in the query string.

curl -b cookies -c cookies 'https://api.appnexus.com/line-item?advertiser_id=100&flight_info=true&min_last_run=2012-01-01 00:00:00&max_last_run=2012-08-01 00:00:00'

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

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

Pass show_alerts=true in the query string. This parameter will add the alerts object to every line item in the response, whether or not the line item has pauses.

Note

For each of the use cases below, you must pass show_alerts=true if you want the alerts object to show up in the response.

$ curl -b cookies -c cookies 'https://api.appnexus.com/line-item?show_alerts=true'

{
    "response": {
        "status": "OK",
        "line-items": [

            {
                "id": 45047,
                "code": null,
                "name": "Line Item 1",
                "advertiser_id": 35081,
                "state": "active",
                "start_date": "2012-04-01 00:00:00",
                "end_date": "2012-05-01 00:00:00",
                ...
                "alerts": {
                    "warnings": [

                    ],
                    "pauses": [
                        {
                            "id": 4,
                            "message": "Flight end date is in the past."
                        }
                    ],
                    "warnings_last_checked": null,
                    "pauses_last_checked": "2012-07-27 19:01:07"
                }
            },
            {
                "id": 45048,
                "code": null,
                "name": "Line Item 2",
                "advertiser_id": 35081,
                "state": "inactive",
                "start_date": "2012-05-21 00:00:00",
                "end_date": null,
                ...
                "alerts": {
                    "warnings": [

                    ],
                    "pauses": [
                        {
                            "id": 1,
                            "message": "State is set to inactive."
                        }
                    ],
                    "warnings_last_checked": null,
                    "pauses_last_checked": "2012-07-27 19:01:07"
                }
            },
            {
                "id": 46308,
                "code": null,
                "name": "Test Line Item",
                "advertiser_id": 45278,
                "state": "inactive",
                "start_date": "2012-06-06 00:00:00",
                "end_date": null,
                ...
                "alerts": {
                    "warnings": [

                    ],
                    "pauses": [
                        {
                            "id": 1,
                            "message": "State is set to inactive."
                        }
                    ],
                    "warnings_last_checked": null,
                    "pauses_last_checked": "2012-07-27 19:01:07"
                }
            },
            ...
        ],
        ...
        }
    }
}

Retrieve only line items that have at least one pause

Pass show_alerts=true&pauses=true in the query string.

$ curl -b cookies -c cookies 'https://api.appnexus.com/line-item?show_alerts=true&pauses=true'

{
    "response": {
        "status": "OK",
        "line-items": [
            {
                "id": 45047,
                "code": null,
                "name": "Line Item 1",
                "advertiser_id": 35081,
                "state": "active",
                "start_date": "2012-04-01 00:00:00",
                "end_date": "2012-05-01 00:00:00",
                ...
                "alerts": {
                    "warnings": [

                    ],
                    "pauses": [
                        {
                            "id": 4,
                            "message": "Flight end date is in the past."
                        }
                    ],
                    "warnings_last_checked": null,
                    "pauses_last_checked": "2012-07-27 19:01:07"
                }
            },
            {
                "id": 45048,
                "code": null,
                "name": "Line Item 2",
                "advertiser_id": 35081,
                "state": "inactive",
                "start_date": "2012-05-21 00:00:00",
                "end_date": null,
                ...
                "alerts": {
                    "warnings": [

                    ],
                    "pauses": [
                        {
                            "id": 1,
                            "message": "State is set to inactive."
                        }
                    ],
                    "warnings_last_checked": null,
                    "pauses_last_checked": "2012-07-27 19:01:07"
                }
            },
            {
                "id": 46308,
                "code": null,
                "name": "Line Item 6",
                "advertiser_id": 45278,
                "state": "inactive",
                "start_date": "2012-06-06 00:00:00",
                "end_date": null,
                ...
                "alerts": {
                    "warnings": [

                    ],
                    "pauses": [
                        {
                            "id": 1,
                            "message": "State is set to inactive."
                        }
                    ],
                    "warnings_last_checked": null,
                    "pauses_last_checked": "2012-07-27 19:01:07"
                }
            },
            ...
        ],
        ...
        }
    }
}

Retrieve only line items that have no pauses

Pass show_alerts=true&pauses=false in the query string.

$ curl -b cookies -c cookies 'https://api.appnexus.com/line-item?show_alerts=true&pauses=false'

{
    "response": {
        "status": "OK",
        "line-items": [
            {
                "id": 45054,
                "code": null,
                "name": "Line Item 7",
                "advertiser_id": 35081,
                "state": "active",
                "start_date": "2012-04-01 00:00:00",
                "end_date": "2012-05-01 00:00:00",
                ...
                "alerts": {
                    "warnings": [

                    ],
                    "pauses": [

                    ],
                    "warnings_last_checked": null,
                    "pauses_last_checked": "2012-07-27 19:01:07"
                }
            },
            {
                "id": 45057,
                "code": null,
                "name": "Line Item 9",
                "advertiser_id": 35081,
                "state": "active",
                "start_date": "2012-05-21 00:00:00",
                "end_date": null,
                ...
                "alerts": {
                    "warnings": [

                    ],
                    "pauses": [

                    ],
                    "warnings_last_checked": null,
                    "pauses_last_checked": "2012-07-27 19:01:07"
                }
            },
            {
                "id": 46345,
                "code": null,
                "name": "Line Item 12",
                "advertiser_id": 45278,
                "state": "active",
                "start_date": "2012-06-06 00:00:00",
                "end_date": null,
                ...
                "alerts": {
                    "warnings": [

                    ],
                    "pauses": [

                    ],
                    "warnings_last_checked": null,
                    "pauses_last_checked": "2012-07-27 19:01:07"
                }
            },
            ...
        ],
        ...
        }
    }
}

Retrieve only line items that have a specific pause

Pass show_alerts=true&pauses=PAUSE_ID in the query string. For pause IDs, see the Pauses table below.

In this example, we use pause ID 2 to retrieve all line items with flight start dates that are in the future.

$ curl -b cookies -c cookies 'https://api.appnexus.com/line-item?show_alerts=true&pauses=2'

{
    "response": {
        "status": "OK",
        "line-items": [
            {
                "id": 45047,
                "code": null,
                "name": "Line Item 5",
                "advertiser_id": 35081,
                "state": "active",
                "start_date": "2012-11-01 00:00:00",
                "end_date": null,
                ...
                "alerts": {
                    "warnings": [

                    ],
                    "pauses": [
                        {
                            "id": 2,
                            "message": "Flight start is in the future."
                        }
                    ],
                    "warnings_last_checked": null,
                    "pauses_last_checked": "2012-07-27 19:01:07"
                }
            },
            {
                "id": 45048,
                "code": null,
                "name": "Line Item 7",
                "advertiser_id": 35081,
                "state": "active",
                "start_date": "2012-10-15 00:00:00",
                "end_date": null,
                ...
                "alerts": {
                    "warnings": [

                    ],
                    "pauses": [
                        {
                            "id": 2,
                            "message": "Flight start is in the future."
                        }
                    ],
                    "warnings_last_checked": null,
                    "pauses_last_checked": "2012-07-27 19:01:07"
                }
            },

            ...
        ],
        ...
        }
    }
}

Retrieve only line items that have two or more specific pauses

Pass show_alerts=true&pauses=SUM_OF_PAUSE_IDS in the query string. For pause IDs, see the Pauses table below.

In this example, we add together pause ID 1 and pause ID 2 to retrieve all line items that are set to inactive and have a flight state date in the future.

$ curl -b cookies -c cookies 'https://api.appnexus.com/line-item?show_alerts=true&pauses=3'

{
    "response": {
        "status": "OK",
        "line-items": [
            {
                "id": 45047,
                "code": null,
                "name": "Line Item 3",
                "advertiser_id": 35081,
                "state": "inactive",
                "start_date": "2012-11-01 00:00:00",
                "end_date": null,
                ...
                "alerts": {
                    "warnings": [

                    ],
                    "pauses": [
                        {
                            "id": 1,
                            "message": "State is set to inactive."
                        },
                        {
                            "id": 2,
                            "message": "Flight start is in the future."
                        }
                    ],
                    "warnings_last_checked": null,
                    "pauses_last_checked": "2012-07-27 19:01:07"
                }
            },
            {
                "id": 45048,
                "code": null,
                "name": "Line Item 7",
                "advertiser_id": 35081,
                "state": "inactive",
                "start_date": "2012-10-15 00:00:00",
                "end_date": null,
                ...
                "alerts": {
                    "warnings": [

                    ],
                    "pauses": [
                        {
                            "id": 1,
                            "message": "State is set to inactive."
                        },
                        {
                            "id": 2,
                            "message": "Flight start is in the future."
                        }
                    ],
                    "warnings_last_checked": null,
                    "pauses_last_checked": "2012-07-27 19:01:07"
                }
            },

            ...
        ],
        ...
        }
    }
}

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

In this example, we'll update a line item to use a CPC performance goal. We're setting a cost-per-click goal threshold of $3.

$ cat line-item
{
    "line-item": {
    "name": "Weekday French Speakers Q3 2012",
    "state": "inactive",
    "comments": "The name says it all -- that's who we're trying to advertise to",
    "daily_budget": null,
    "revenue_type": "cpm",
    "goal_type": "cpc",
    "valuation": {
        "goal_target":3,
        "goal_threshold":3
    }
    "lifetime_budget": null,
    "end_date": null,
    "enable_pacing": null,
    "allow_safety_pacing": null,
    "publishers_allowed": "all"
    }
}

curl -b cookies -c cookies -X PUT -d @line-item "https://api.appnexus.com/line-item?id=152083&advertiser_id=51"

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

In this example, we'll update a line item to use both a CPC and CPA performance goal. We're setting the CPC goal of $5 and the CPA goal to $10.

$ cat line-item
{
    "line-item": {
    "name": "Weekday French Speakers Q3 2012",
    "state": "inactive",
    "comments": "The name says it all -- that's who we're trying to advertise to",
    "daily_budget": null,
    "revenue_type": "cpm",
    "goal_type": "cpa",
    "pixels": [
        {
        "id": "123456"
        }
    ],
    "goal_pixels":[
        {
        "id":"123456",
        "post_click_goal_threshold":10,
        "post_click_goal_target":10
        }
    ],
    “valuation”: {
        “goal_target”: 5,
        “goal_threshold”: 5
        }
    }
}

curl -b cookies -X PUT -d @line-item "https://api.appnexus.com/line-item?id=152083&advertiser_id=51"

View a line item

To view a specific line item, we must pass in the line item and advertiser IDs via the query string.

$ curl -b cookies -c cookies 'https://api.appnexus.com/line-item?id=4979347&advertiser_id=1887392'
{
    "response": {
        "count": 1,
        "dbg_info": {
            "output_term": "line-item",
            "version": "1.18.227",
            "warnings": []
        },
        "line-item": {
            "ad_types": [
                "banner"
            ],
            "advertiser": {
                "id": 1887392,
                "name": "ALI Closed Beta Demo Advertiser"
            },
            "advertiser_id": 1887392,
            "allow_safety_pacing": null,
            "auction_event": null,
            "bid_object_type": "creative",
            "broker_fees": null,
            "budget_intervals": [
                {
                    "code": null,
                    "enable_pacing": true,
                    "end_date": "2017-12-02 23:59:59",
                    "id": 2509919,
                    "lifetime_budget": 1,
                    "lifetime_budget_imps": null,
                    "lifetime_pacing": true,
                    "lifetime_pacing_pct": 100,
                    "object_id": 4979347,
                    "object_type": "campaign_group",
                    "parent_interval_id": null,
                    "start_date": "2017-11-30 00:00:00",
                    "timezone": "US/Eastern"
                }
            ],
            "budget_set_per_flight": true,
            "campaigns": null,
            "click_url": null,
            "clicktrackers": null,
            "code": null,
            "comments": null,
            "creative_distribution_type": null,
            "creatives": null,
            "currency": "USD",
            "custom_models": [
                {
                    "active": "1",
                    "id": 477441,
                    "name": "cadence 2017-11-07 18:03:37.738",
                    "type": "cadence"
                }
            ],
            "custom_optimization_note": null,
            "daily_budget": null,
            "daily_budget_imps": null,
            "deals": null,
            "delivery_goal": null,
            "discrepancy_pct": 0,
            "enable_pacing": null,
            "enable_v8": false,
            "end_date": null,
            "goal_pixels": [
                {
                    "id": 932952,
                    "name": "Test Pixel",
                    "post_click_goal": null,
                    "post_click_goal_confidence_threshold": null,
                    "post_click_goal_target": 10,
                    "post_click_goal_threshold": 10,
                    "post_click_model_id": null,
                    "post_view_goal": null,
                    "post_view_goal_confidence_threshold": null,
                    "post_view_goal_target": null,
                    "post_view_goal_threshold": null,
                    "post_view_model_id": null,
                    "state": "active",
                    "trigger_type": "hybrid"
                }
            ],
            "goal_type": "cpc",
            "goal_value": null,
            "id": 4979347,
            "imptrackers": null,
            "incrementality": null,
            "insertion_orders": [
                {
                    "advertiser_id": 1887392,
                    "budget_intervals": [
                        {
                            "code": null,
                            "daily_budget": null,
                            "daily_budget_imps": null,
                            "enable_pacing": false,
                            "end_date": null,
                            "id": 2509856,
                            "lifetime_budget": 1,
                            "lifetime_budget_imps": null,
                            "lifetime_pacing": false,
                            "object_id": 676605,
                            "object_type": "insertion_order",
                            "start_date": "2017-11-30 00:00:00",
                            "timezone": "US/Eastern"
                        }
                    ],
                    "code": null,
                    "currency": "USD",
                    "end_date": null,
                    "id": 676605,
                    "last_modified": "2017-12-01 02:44:34",
                    "name": "Swetha_Seamless_IO",
                    "start_date": null,
                    "state": "active",
                    "timezone": "US/Eastern"
                }
            ],
            "inventory_discovery": {
                "fail_criteria_amount": 9.486486,
                "fail_criteria_type": "booked_revenue",
                "use_ranked_discovery": true
            },
            "inventory_discovery_budget": null,
            "inventory_type": "real_time",
            "labels": null,
            "last_modified": "2017-12-02 05:30:29",
            "lifetime_budget": null,
            "lifetime_budget_imps": null,
            "lifetime_pacing": null,
            "lifetime_pacing_pct": null,
            "lifetime_pacing_span": null,
            "line_item_type": "standard_v2",
            "manage_creative": true,
            "member_id": 1370,
            "name": "Swetha_ALI_Basic_API1",
            "pixels": [
                {
                    "id": 932952,
                    "name": "Test Pixel",
                    "post_click_revenue": null,
                    "post_view_revenue": null,
                    "state": "active",
                    "trigger_type": "hybrid"
                }
            ],
            "prefer_delivery_over_performance": false,
            "priority": "5",
            "profile_id": 96266622,
            "publishers_allowed": "all",
            "remaining_days": null,
            "require_cookie_for_tracking": true,
            "revenue_type": "vcpm",
            "revenue_value": null,
            "roadblock": null,
            "start_date": null,
            "state": "active",
            "timezone": "US/Eastern",
            "total_days": null,
            "valuation": {
                "bid_price_pacing_enabled": false,
                "bid_price_pacing_lever": 0,
                "goal_confidence_threshold": null,
                "goal_target": 5,
                "goal_threshold": 5,
                "max_avg_cpm": 3,
                "max_revenue_value": null,
                "min_avg_cpm": 2,
                "min_margin_pct": null,
                "min_revenue_value": null,
                "no_revenue_log": false
            }
        },
        "num_elements": 100,
        "start_element": 0,
        "status": "OK"
    }
}

View all of an advertiser's line items

Unlike the examples above, this line item has a goal_pixels array of objects attached. Notice that even though this advertiser has only one line item, it's returned via the line-items JSON array.

$ curl -b cookies 'https://api.appnexus.com/line-item?advertiser_id=51'
{
    "response": {
        "count": 3,
        "line-items": [
            { ..."id": 4274691,...},
            { ..."id": 4983291,...},
            { ..."id": 4983258,...}
        ]
    }
}

Create a line item with a CPM revenue type, optimized to a CPA goal (post-click and post-view conversions)

cat li_cpa.json

{
    "line-item": {
    "name": "LI CPA Test",
    "state": "inactive",
    "daily_budget": null,
    "revenue_type": "cpm",
    "goal_type": "cpa",
    "goal_pixels": [
        {
            "id": 987654321,
            "name": "Confirmation Page",
            "post_click_goal": null,
            "post_click_goal_confidence_threshold": null,
            "post_click_goal_target": 1,
            "post_click_goal_threshold": 1,
            "post_click_model_id": null,
            "post_view_goal": null,
            "post_view_goal_confidence_threshold": null,
            "post_view_goal_target": 1,
            "post_view_goal_threshold": 1,
            "post_view_model_id": null,
            "state": "active",
            "trigger_type": "hybrid"
                }
            ], 
    "valuation": {
        "bid_price_pacing_enabled": false,
        "bid_price_pacing_lever": 0,
        "campaign_group_valuation_strategy": "retargeting",
        "goal_confidence_threshold": null,
        "goal_target": null,
        "goal_threshold": null,
        "max_avg_cpm": null,
        "max_revenue_value": null,
        "min_avg_cpm": null,
        "min_margin_pct": null,
        "min_revenue_value": null,
        "no_revenue_log": false
            },
}

$curl -b cookies -X POST -d @li_cpa.json 'https://api.appnexus.com/line-item?advertiser_id=12345'
{
    "response": {
        "count": 1,
        "dbg_info": {
            "output_term": "line-item",
            "version": "1.18.1023",
            "warnings": []
        },
        "line-item": {
            "ad_types": [
                "banner"
            ],
            "advertiser": {
                "id": 12345,
                "name": "Console Challenge (Please Do Not Modify)"
            },
            "advertiser_id": 12345,
            "allow_safety_pacing": null,
            "archived_on": null,
            "auction_event": {
                "kpi_auction_event_type": "impression",
                "kpi_auction_event_type_code": "impression",
                "kpi_auction_type_id": 1,
                "kpi_value": null,
                "payment_auction_event_type": "impression",
                "payment_auction_event_type_code": "impression",
                "payment_auction_type_id": 1,
                "revenue_auction_event_type": "impression",
                "revenue_auction_event_type_code": "impression",
                "revenue_auction_type_id": 1
            },
            "bid_object_type": "creative",
            "broker_fees": null,
            "budget_intervals": [
                {
                    "code": null,
                    "enable_pacing": true,
                    "end_date": "2019-02-11 23:59:59",
                    "id": 3886503,
                    "lifetime_budget": 0.01,
                    "lifetime_budget_imps": null,
                    "lifetime_pacing": true,
                    "lifetime_pacing_pct": 100,
                    "object_id": 7358523,
                    "object_type": "campaign_group",
                    "parent_interval_id": null,
                    "start_date": "2019-02-10 00:00:00",
                    "timezone": "US/Eastern"
                }
            ],
            "budget_set_per_flight": false,
            "campaigns": null,
            "click_url": null,
            "clicktrackers": null,
            "code": null,
            "comments": null,
            "creative_distribution_type": "ctr-optimized",
            "creatives": null,
            "currency": "USD",
            "custom_models": [
                {
                    "active": "1",
                    "experiment": "control",
                    "id": 222333,
                    "name": "Test 001",
                    "origin": "optimization",
                    "type": "conv_imp"
                },
                {
                    "active": "1",
                    "experiment": "control",
                    "id": 222334,
                    "name": "Test 002",
                    "origin": "optimization",
                    "type": "cadence"
                },
                {
                    "active": "1",
                    "experiment": "control",
                    "id": 222335,
                    "name": "Budget Splitter - 7358523 - Mon Feb 11 2019 04:08:49 GMT+0000",
                    "origin": "splitters",
                    "type": "budget_splitter"
                }
            ],
            "custom_optimization_note": null,
            "daily_budget": null,
            "daily_budget_imps": null,
            "deals": null,
            "delivery_goal": null,
            "discrepancy_pct": 0,
            "enable_pacing": null,
            "enable_v8": false,
            "end_date": null,
            "flat_fee": null,
            "flat_fee_type": null,
            "goal_pixels": [
                {
                    "id": 987654321,
                    "name": "Confirmation Page",
                    "post_click_goal": null,
                    "post_click_goal_confidence_threshold": null,
                    "post_click_goal_target": 1,
                    "post_click_goal_threshold": 1,
                    "post_click_model_id": null,
                    "post_view_goal": null,
                    "post_view_goal_confidence_threshold": null,
                    "post_view_goal_target": 1,
                    "post_view_goal_threshold": 1,
                    "post_view_model_id": null,
                    "state": "active",
                    "trigger_type": "hybrid"
                }
            ],
            "goal_type": "cpa",
            "goal_value": null,
            "id": 87654321,
            "imptrackers": null,
            "incrementality": null,
            "insertion_orders": [
                {
                    "advertiser_id": 12345,
                    "budget_intervals": [
                        {
                            "code": null,
                            "daily_budget": null,
                            "daily_budget_imps": null,
                            "enable_pacing": false,
                            "end_date": "2018-05-31 23:59:59",
                            "id": 2957582,
                            "lifetime_budget": 100,
                            "lifetime_budget_imps": null,
                            "lifetime_pacing": false,
                            "object_id": 811332,
                            "object_type": "insertion_order",
                            "start_date": "2018-05-23 00:00:00",
                            "timezone": "US/Eastern"
                        },
                        {
                            "code": null,
                            "daily_budget": null,
                            "daily_budget_imps": null,
                            "enable_pacing": false,
                            "end_date": "2018-09-24 23:59:59",
                            "id": 3331427,
                            "lifetime_budget": 100,
                            "lifetime_budget_imps": null,
                            "lifetime_pacing": false,
                            "object_id": 811332,
                            "object_type": "insertion_order",
                            "start_date": "2018-09-23 00:00:00",
                            "timezone": "US/Eastern"
                        },
                        {
                            "code": null,
                            "daily_budget": null,
                            "daily_budget_imps": null,
                            "enable_pacing": false,
                            "end_date": "2018-11-30 23:59:59",
                            "id": 3494586,
                            "lifetime_budget": 600,
                            "lifetime_budget_imps": null,
                            "lifetime_pacing": false,
                            "object_id": 811332,
                            "object_type": "insertion_order",
                            "start_date": "2018-10-31 00:00:00",
                            "timezone": "US/Eastern"
                        },
                        {
                            "code": null,
                            "daily_budget": null,
                            "daily_budget_imps": null,
                            "enable_pacing": false,
                            "end_date": "2018-12-12 23:59:59",
                            "id": 3636004,
                            "lifetime_budget": 300,
                            "lifetime_budget_imps": null,
                            "lifetime_pacing": false,
                            "object_id": 811332,
                            "object_type": "insertion_order",
                            "start_date": "2018-12-07 00:00:00",
                            "timezone": "US/Eastern"
                        },
                        {
                            "code": null,
                            "daily_budget": null,
                            "daily_budget_imps": null,
                            "enable_pacing": false,
                            "end_date": "2019-01-14 23:59:59",
                            "id": 3746556,
                            "lifetime_budget": 400,
                            "lifetime_budget_imps": null,
                            "lifetime_pacing": false,
                            "object_id": 811332,
                            "object_type": "insertion_order",
                            "start_date": "2019-01-07 00:00:00",
                            "timezone": "US/Eastern"
                        },
                        {
                            "code": null,
                            "daily_budget": null,
                            "daily_budget_imps": null,
                            "enable_pacing": false,
                            "end_date": "2019-01-22 23:59:59",
                            "id": 3773032,
                            "lifetime_budget": 0.01,
                            "lifetime_budget_imps": null,
                            "lifetime_pacing": false,
                            "object_id": 811332,
                            "object_type": "insertion_order",
                            "start_date": "2019-01-15 00:00:00",
                            "timezone": "US/Eastern"
                        },
                        {
                            "code": null,
                            "daily_budget": null,
                            "daily_budget_imps": null,
                            "enable_pacing": false,
                            "end_date": "2019-02-06 23:59:59",
                            "id": 3857762,
                            "lifetime_budget": 0.01,
                            "lifetime_budget_imps": null,
                            "lifetime_pacing": false,
                            "object_id": 811332,
                            "object_type": "insertion_order",
                            "start_date": "2019-02-04 00:00:00",
                            "timezone": "US/Eastern"
                        },
                        {
                            "code": null,
                            "daily_budget": null,
                            "daily_budget_imps": null,
                            "enable_pacing": false,
                            "end_date": "2019-02-28 23:59:59",
                            "id": 3886493,
                            "lifetime_budget": 600,
                            "lifetime_budget_imps": null,
                            "lifetime_pacing": false,
                            "object_id": 811332,
                            "object_type": "insertion_order",
                            "start_date": "2019-02-10 00:00:00",
                            "timezone": "US/Eastern"
                        }
                    ],
                    "code": null,
                    "currency": "USD",
                    "end_date": null,
                    "id": 811332,
                    "last_modified": "2019-02-25 15:36:24",
                    "name": "Natasha Test IO",
                    "start_date": null,
                    "state": "active",
                    "timezone": "US/Eastern"
                }
            ],
            "inventory_discovery": null,
            "inventory_type": "both",
            "is_archived": false,
            "labels": null,
            "last_modified": "2019-03-01 21:12:45",
            "lifetime_budget": null,
            "lifetime_budget_imps": null,
            "lifetime_pacing": null,
            "lifetime_pacing_pct": null,
            "lifetime_pacing_span": null,
            "line_item_type": "standard_v2",
            "manage_creative": true,
            "member_id": 1370,
            "name": "Copy test2_01_17",
            "pixels": [
                {
                    "id": 1017110,
                    "name": "Confirmation Page",
                    "post_click_revenue": null,
                    "post_view_revenue": null,
                    "state": "active",
                    "trigger_type": "hybrid"
                }
            ],
            "prefer_delivery_over_performance": false,
            "priority": "5",
            "profile_id": 109625231,
            "publishers_allowed": "all",
            "remaining_days": null,
            "require_cookie_for_tracking": true,
            "revenue_type": "cpm",
            "revenue_value": 1,
            "roadblock": null,
            "start_date": null,
            "state": "inactive",
            "supply_strategies": {
                "deals": false,
                "managed": false,
                "rtb": true
            },
            "timezone": "US/Eastern",
            "total_days": null,
            "user_info": {
                "creator_id": 17707,
                "owner_id": 17707
            },
            "valuation": {
                "bid_price_pacing_enabled": false,
                "bid_price_pacing_lever": 0,
                "campaign_group_valuation_strategy": "retargeting",
                "goal_confidence_threshold": null,
                "goal_target": null,
                "goal_threshold": null,
                "max_avg_cpm": null,
                "max_revenue_value": null,
                "min_avg_cpm": null,
                "min_margin_pct": null,
                "min_revenue_value": null,
                "no_revenue_log": false
            },
            "viewability_vendor": "appnexus"
        },
        "num_elements": 100,
        "start_element": 0,
        "status": "OK"
    }
}

Create a line item with a revenue type of Dynamic CPM and optimized to a CPC goal

In this example, we set the CPC goal to $5 and minimum average CPM to $2 and maximum average CPM to $3.

{code}$ cat line_item_dcp_cpc
{
  "line-item": {
    "ad_types": [
      "banner"
     ],
    "advertiser": {
      "id": 1887392,
      "name": "ALI Closed Beta Demo Advertiser"
     },
    "currency": "USD",
    "insertion_orders": [{
      "advertiser_id": 1887392,
      "budget_intervals": [{
            "code": null,
            "daily_budget": null,
            "daily_budget_imps": null,
            "enable_pacing": false,
            "end_date": null,
            "id": 2509856,
            "lifetime_budget": 1,
            "lifetime_budget_imps": null,
            "lifetime_pacing": false,
            "object_id": 676605,
            "object_type": "insertion_order",
            "start_date": "2017-11-30 00:00:00",
            "timezone": "US/Eastern"
        }],
        "code": null,
        "currency": "USD",
        "end_date": null,
        "id": 676605,
        "last_modified": "2017-12-01 02:44:34",
        "name": "Swetha_Seamless_IO",
        "start_date": null,
        "state": "active",
        "timezone": "US/Eastern"
    }],
    "advertiser_id": 1887392,
    "budget_intervals": [{
        "code": null,
        "enable_pacing": true,
        "end_date": "2017-12-02 23:59:59",
        "lifetime_budget": 1,
        "lifetime_budget_imps": null,
        "lifetime_pacing": true,
        "lifetime_pacing_pct": 100,
        "parent_interval_id": null,
        "start_date": "2017-11-30 00:00:00",
        "timezone": "US/Eastern"
    }],
        "goal_pixels": null,
        "goal_type": "cpc",
        "goal_value": null,
        "inventory_type": "real_time",
        "line_item_type": "standard_v2",
        "manage_creative": true,
        "name": "Swetha_ALI_Basic_API1",
        "profile_id": 96266482,
        "revenue_type": "vcpm",
        "revenue_value": null,
        "state": "active",
        "valuation": {
            "goal_target": 5,
            "goal_threshold": 5,
            "min_avg_cpm": 2,
            "max_avg_cpm": 3
        }
    }
}
{code}

{code}
curl -b cookies -X POST -d  @line_item_dcp_cpc.json  "https://api.appnexus.com/line-item?&advertiser_id=1887392"
{code}

Create a line item with a revenue type of Viewable CPM and optimized to both a CPC and CPA goal

In this example, we create a line item with a revenue type of Viewable CPM, a CPC goal of $5 and CPA goal of $10.

{code}$ cat line_item_dcp_vcpm_cpaopt
{
    "line-item": {
        "ad_types": [
            "banner"
        ],
        "advertiser": {
            "id": 1887392,
            "name": "ALI Closed Beta Demo Advertiser"
        },
        "currency": "USD",
        "insertion_orders": [{
            "advertiser_id": 1887392,
            "budget_intervals": [{
                "code": null,
                "daily_budget": null,
                "daily_budget_imps": null,
                "enable_pacing": false,
                "end_date": null,
                "id": 2509856,
                "lifetime_budget": 1,
                "lifetime_budget_imps": null,
                "lifetime_pacing": false,
                "object_id": 676605,
                "object_type": "insertion_order",
                "start_date": "2017-11-30 00:00:00",
                "timezone": "US/Eastern"
            }],
            "code": null,
            "currency": "USD",
            "end_date": null,
            "id": 676605,
            "last_modified": "2017-12-01 02:44:34",
            "name": "Swetha_Seamless_IO",
            "start_date": null,
            "state": "active",
            "timezone": "US/Eastern"
        }],

        "advertiser_id": 1887392,
        "budget_intervals": [{
            "code": null,
            "enable_pacing": true,
            "end_date": "2017-12-02 23:59:59",
            "lifetime_budget": 1,
            "lifetime_budget_imps": null,
            "lifetime_pacing": true,
            "lifetime_pacing_pct": 100,
            "parent_interval_id": null,
            "start_date": "2017-11-30 00:00:00",
            "timezone": "US/Eastern"
        }],
        "goal_type": "cpa",
        "goal_value": null,
        "inventory_type": "real_time",
        "line_item_type": "standard_v2",
        "manage_creative": true,
        "name": "Swetha_ALI_VCPM_CPA",
        "profile_id": 96293804,
        "revenue_type": "cpm",
        "revenue_value": 3,
        "state": "active",
        "goal_pixels": [{
            "id": 932952,
            "post_click_goal_target": 10,
            "post_click_goal_threshold": 10
        }],
        "pixels": [{
            "id": 932952
        }],

        "valuation": {
            "goal_target": 5,
            "goal_threshold": 5
        },
        "auction_event": {
            "revenue_auction_event_type": "view",
            "revenue_auction_event_type_code": "view_display_50pv1s_an",
            "revenue_auction_type_id": 2}
    }
}
{code}

{code}
curl -b cookies -X POST -d @line_item_dcp_vcpm_cpaopt.json “https://api.appnexus.com/line-item?&advertiser_id=1887392”
{code}

Create a line item with a CPM revenue type, optimized to a VCR goal

In this example, we set the VCR goal to 50% and the CPM revenue value to $3.

Note

Managed supply strategy must be set to false to apply a VCR goal to the line item. VCR optimization is not supported for line items targeting managed inventory.

$ cat line_item_vcr 
{
 "line-item": {
 
     "ad_types": [
         "video"
     ],
     "advertiser": {
         "id": 4127136,
         "name": "VCR Test Advertiser"
     },
     "advertiser_id": 4127136,
     "inventory_type": "both",
     "name": "Test VCR LI",
     "state": "active",
     "currency": "USD",
     "timezone": "US/Eastern",
     "revenue_type": "cpm",
     "revenue_value": 3,
     "supply_strategies": {
         "managed": false,
         "rtb": true,
         "deals": false,
         "programmatic_guaranteed": false
     },
     "goal_type": "none",
     "budget_intervals": [
         {
             "id": 12024043,
             "object_id": 14286184,
             "object_type": "campaign_group",
             "start_date": "2021-03-19 00:00:00",
             "end_date": "2021-04-30 23:59:59",
             "timezone": "US/Eastern",
             "code": null,
             "parent_interval_id": null,
             "creatives": null,
             "subflights": null,
             "lifetime_budget": 2,
             "lifetime_budget_imps": null,
             "lifetime_pacing": true,
             "enable_pacing": true,
             "lifetime_pacing_pct": 100,
             "daily_budget_imps_opt": null,
             "daily_budget_opt": null
         }
     ],
     "insertion_orders": [
         {
             "id": 3205367,
             "state": "inactive"
             "name": "VCR Test IO",
             "advertiser_id": 4127136,
             "currency": "USD",
             "budget_intervals": [
                 {
                     "id": 6461220,
                     "object_id": 3205367,
                     "object_type": "insertion_order",
                     "start_date": "2019-11-30 00:00:00",
                     "end_date": "2019-12-31 23:59:59",
                     "timezone": "US/Eastern",
                     "code": null,
                     "lifetime_budget": 1,
                     "lifetime_budget_imps": null,
                     "lifetime_pacing": false,
                     "enable_pacing": false,
                     "daily_budget_imps": null,
                     "daily_budget": null,
                     "daily_budget_imps_opt": null,
                     "daily_budget_opt": null
                 }
             ],
         }
     ],
     "auction_event": {
         "payment_auction_event_type_code": "impression",
         "payment_auction_event_type": "impression",
         "payment_auction_type_id": 1,
         "revenue_auction_event_type_code": "impression",
         "revenue_auction_event_type": "impression",
         "revenue_auction_type_id": 1,
         "kpi_auction_event_type_code": "video_completion",
         "kpi_auction_event_type": "video",
         "kpi_auction_type_id": 10,
         "kpi_value_type": "rate_threshold",
         "kpi_value": 0.5
     },
     "valuation": {
         "min_margin_pct": null,
         "min_margin_cpm": null,
         "max_avg_cpm": null,
         "min_avg_cpm": null,
         "min_revenue_value": null,
         "max_revenue_value": null,
         "goal_target": null,
         "goal_threshold": null,
         "no_revenue_log": false,
         "bid_price_pacing_enabled": false,
         "bid_price_pacing_lever": 0,
         "campaign_group_valuation_strategy": null,
         "goal_confidence_threshold": null
     }
  } 
} 

Update a line item to optimize to a Viewable CPM goal

In this example, we are updating a line item to optimize to is a Viewable CPM goal of $5.

{code}$ cat line_item_vcpmopt.json
{
    "line-item": {
        "goal_type": "none",
        "goal_value": null,
        "name": "ALI_VCPMOpt",
        "state": "active",
        "goal_pixels": null,
        "auction_event": {
            "kpi_auction_event_type": "view",
            "kpi_auction_event_type_code": "view_display_50pv1s_an",
            "kpi_auction_type_id": 2,
            "kpi_value": 5
        }
    }
}
{code}

{code}
curl -b cookies -X PUT -d @line_item_vcpmopt.json "https://api.appnexus.com/line-item?id=152083&advertiser_id=1887392"
{code}

Update a line item to use a revenue type of Viewable CPM

In this example, we are updating a line item to use a Revenue Type of VCPM and setting the value to $3.

{code}$ cat lineitem_vcpm.json
{
    "line-item": {
        "goal_type": "none",
        "goal_value": null,
        "inventory_type": "real_time",
        "line_item_type": "standard_v2",
        "revenue_type": "cpm",
        "revenue_value": 3,
        "state": "active",
        "auction_event": {               
            "revenue_auction_event_type": "view",
            "revenue_auction_event_type_code": "view_display_50pv1s_an",
            "revenue_auction_type_id": 2}
    }
}
{code}

{code}
curl -b cookies -X PUT -d @lineitem_vcpm.json "https://api.appnexus.com/line-item?id=152083&advertiser_id=1887392"
{code}

Update a line item to use a revenue type of CPC

In this example, we are updating a line item to use a Revenue Type of CPC and setting the revenue value to $3.

{code}$ cat line_item_cpc.json
{
    "line-item": {
        "inventory_type": "real_time",
        "line_item_type": "standard_v2",
        "revenue_type": "cpm",
        "revenue_value": 3,
        "state": "active",
        "auction_event": {
        "revenue_auction_event_type": "click",
        "revenue_auction_event_type_code": "click",
        "revenue_auction_type_id": 3
        }
    }
}
{code}
{code}
curl -b cookies -X PUT -d @line_item_cpc.json "https://api.appnexus.com/line-item?id=152083&advertiser_id=1887392"
{code}

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

In this example, we are updating a line item to use a Revenue Type of Cost Plus Margin with a margin of 20% and with optimization disabled. The CPM is a flat CPM of 11.

{code}$ cat line_item_costplus_base.json
{
    "line-item": {
        "goal_type": "none",
        "goal_value": null,
        "inventory_type": "real_time",
        "line_item_type": "standard_v2",
        "revenue_type": "cost_plus_margin",
        "revenue_value": 0.20,
        "state": "active",
        "goal_pixels": null,
        "valuation":{"max_avg_cpm": 11}
    }
}
{code}

{code}
curl -b cookies -X PUT -d @line_item_costplus_base.json "https://api.appnexus.com/line-item?id=152083&advertiser_id=1887392"
{code}

Update a line item to disable optimization

In this example, we are updating a line item to disable optimiztion.

{code}$ cat line_item_no_opt.json
{
    "line-item": {
        "auction_event": {
        "kpi_auction_event_type": "impression",
        "kpi_auction_event_type_code": "impression",
        "kpi_auction_type_id": 1,
        "kpi_value": null,
        "payment_auction_event_type": "impression",
        "payment_auction_event_type_code": "impression",
        "payment_auction_type_id": 1,
        "revenue_auction_event_type": "impression",
        "revenue_auction_event_type_code": "impression",
        "revenue_auction_type_id": 1
        },
        "goal_pixels": null,
        "goal_type": "none",
        "goal_value": null
    }
}
{code}

{code}
$ curl -b cookies -X PUT -d @line_item_no_opt.json "https://api.appnexus.com/line-item?&id=152083&advertiser_id=1887392"
{code}

Create a Programmatic Guaranteed buying line item

Scenario: You have negotiated a Programmatic Guaranteed deal (PG deal) with a seller and would like to target this deal with a Programmatic Guaranteed buying line item (PG buying line item).

1. Create a PG deal profile and note the ID for this profile (see Target a Programmatic Guaranteed deal example in Profile Service).

2. Create a PG buying line item JSON (you'll need an existing insertion order ID and profile ID).

   $ cat pg_buying_line_item
   {
     "line-item": {
       "insertion_orders": [
         {
           "id": 1234
         }
       ],
       "name": "My PG Buying Line Item",
       "state": "active",
       "ad_types": [
         "banner"
       ],
       "profile_id": 123456,
       "currency": "USD",
       "supply_strategies": {
         "rtb": false,
         "managed": false,
         "deals": false,
         "programmatic_guaranteed": true
       },
       "revenue_value": 0.0,
       "revenue_type": "cost_plus_margin",
       "creatives": [],
       "require_cookie_for_tracking": false,
       "line_item_type": "standard_v2",
       "manage_creative": true
     }
   }
   

3. Make a POST request to the https://api.appnexus.com/line-item endpoint using this PG buying line item JSON and the appropriate advertiser_id.

   $ curl -b cookies -X POST -d @pg_buying_line_item 'https://api.appnexus.com/line-item?advertiser_id=123'
   {
       "response": {
           "status": "OK",
           "count": 1,
           "id": 8757356,
           "start_element": 0,
           "num_elements": 100,
           "line-item": {
               "id": 8757356,
               "code": null,
               "name": "My PG Buying Line Item",
               "advertiser_id": 123,
               "state": "active",
               "start_date": null,
               "end_date": null,
               "timezone": "CET",
               "discrepancy_pct": 0,
               "publishers_allowed": "all",
               "revenue_value": 0,
               "revenue_type": "cost_plus_margin",
               "goal_type": "none",
               "goal_value": null,
               "last_modified": "2019-08-07 19:49:45",
               "click_url": null,
               "currency": "USD",
               "require_cookie_for_tracking": false,
               "profile_id": 123456,
               "member_id": 958,
               "flat_fee_type": null,
               "comments": null,
               "remaining_days": null,
               "total_days": null,
               "manage_creative": true,
               "budget_set_per_flight": true,
               "creative_distribution_type": null,
               "line_item_type": "standard_v2",
               "bid_object_type": "creative",
               "prefer_delivery_over_performance": false,
               "priority": "5",
               "enable_v8": false,
               "viewability_vendor": null,
               "is_archived": false,
               "archived_on": null,
               "delivery_model_type": "standard",
               "advertiser": {
                   "id": 123,
                   "name": "My Advertiser"
               },
               "flat_fee": null,
               "supply_strategies": {
                   "managed": false,
                   "rtb": false,
                   "deals": false,
                   "programmatic_guaranteed": true
               },
               "deals": null,
               "delivery_goal": null,
               "labels": null,
               "broker_fees": null,
               "pixels": null,
               "insertion_orders": [
                   {
                       "id": 1234,
                       "state": "active",
                       "code": null,
                       "name": "Test IO",
                       "advertiser_id": 123,
                       "start_date": null,
                       "end_date": null,
                       "timezone": "CET",
                       "last_modified": "2018-03-06 21:16:47",
                       "currency": "USD",
                       "budget_intervals": [
                           {
                               "id": 2436841,
                               "object_id": 1234,
                               "object_type": "insertion_order",
                               "start_date": "2017-11-08 00:00:00",
                               "end_date": "2017-11-13 23:59:59",
                               "timezone": "CET",
                               "code": null,
                               "lifetime_budget": 10,
                               "lifetime_budget_imps": null,
                               "lifetime_pacing": false,
                               "enable_pacing": false,
                               "daily_budget_imps": null,
                               "daily_budget": null
                           }
                       ]
                   }
               ],
               "goal_pixels": null,
               "imptrackers": null,
               "clicktrackers": null,
               "campaigns": null,
               "valuation": null,
               "creatives": null,
               "budget_intervals": null,
               "custom_models": null,
               "inventory_discovery": null,
               "incrementality": null,
               "auction_event": null,
               "custom_optimization_note": null,
               "roadblock": null,
               "ad_types": null,
               "user_info": null,
               "partner_fees": null,
               "product": null,
               "in_demo_measurement": null,
               "lifetime_budget": null,
               "lifetime_budget_imps": null,
               "daily_budget": null,
               "daily_budget_imps": null,
               "enable_pacing": null,
               "allow_safety_pacing": null,
               "lifetime_pacing": null,
               "lifetime_pacing_span": null,
               "lifetime_pacing_pct": null,
               "inventory_type": "both"
           },
           "dbg_info": {
               "warnings": [],
               "version": "1.18.1247",
               "output_term": "line-item"
           }
       }
   }
   

Delete a line item

curl -b cookies -X DELETE "https://api.appnexus.com/line-item?id=5851054&advertiser_id=5413231"

{"response":
    {
        "status":"OK",
        "count":1,
        "start_element":null,
        "num_elements":null,
        "dbg_info":
            {
                "warnings":[],
                "version":"1.0.190",
                "output_term":"not_found"}
            }
    }
}

Update a line item to optimize for CPCV

In this example, we are updating a line item to optimize to CPCV $0.08.

{code}$ cat line_item_CPCV.json
{
    "line-item": {
        "goal_type": "none",
        "goal_value": null,
        "name": "ALI_CPCV",
        "state": "active",
        "goal_pixels": null,
        "auction_event": {
                "payment_auction_event_type_code": "impression",
                "payment_auction_event_type": "impression",
                "payment_auction_type_id": 1,
                "revenue_auction_event_type_code": "impression",
                "revenue_auction_event_type": "impression",
                "revenue_auction_type_id": 1,
                "kpi_auction_event_type_code": "video_completion",
                "kpi_auction_event_type": "video",
                "kpi_auction_type_id": 10,
                "kpi_value_type": "goal_value",
                "kpi_value": 0.08
            }
    }
}
{code}
{code}
curl -b cookies -X PUT -d @line_item_CPCV.json "https://api.appnexus.com/line-item?id=152083&advertiser_id=1887392"
{code}

A line item that is not optimized for CPCV

In this example, we have a line item that is not optimized for CPCV.

{code}$ cat line_item_CPCV.json
{
    "line-item": {
        "goal_type": "none",
        "goal_value": null,
        "name": "ALI_CPCV",
        "state": "active",
        "goal_pixels": null,
        "auction_event": { 
                "kpi_auction_event_type": "impression", 
                "kpi_auction_event_type_code": "impression", 
                "kpi_auction_type_id": 1, 
                "kpi_value": null, 
                "kpi_value_type": "none", 
                "payment_auction_event_type": "impression",
                "payment_auction_event_type_code": "impression", 
                "payment_auction_type_id": 1, 
                "revenue_auction_event_type": "impression",
                "revenue_auction_event_type_code": 
                "impression", "revenue_auction_type_id": 1 }
    }
}
{code}

{code}
curl -b cookies -X PUT -d @line_item_CPCV.json "https://api.appnexus.com/line-item?id=152083&advertiser_id=1887392"
{code}

Related topics

• API Best Practices
• API Semantics
• Conversion Pixel Service
• Insertion Order Service