Partager via

Digital Platform API - Insertion Order service

  • Article

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

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

Note

Seamless insertion orders

There are two types of insertion orders:

  • Seamless – Seamless insertion order for line items that provide additional targeting and budgeting settings. The budget_type setting of Seamless insertion orders may restrict associated guaranteed delivery augmented line items (GDALI) and programmatic guaranteed line items (PGLI) that have conflicting settings. We recommend using seamless insertion orders with budget_type set to "flexible" for GDALIs and PGLIs so you can associate both impression-based and revenue-based line items to the same insertion order.
  • Legacy (non-seamless) – Legacy insertion order required for legacy guaranteed and non-guaranteed line items. Legacy insertion orders do not use the budget_intervals array and cannot be used with augmented line items (ALI), guaranteed delivery augmented line items (GDALI), and programmatic guaranteed line items (PGLI).

The main differences in setup for each type of insertion order are as follows:

  • To create a Seamless insertion order, you must:

    • Use the budget and pacing related fields and the start_date and end_date fields in the budget_intervals array to specify the dates during which the insertion order should run, what budget is available to it during those dates and how spending of the budget should be paced.
    • Leave the start_date and end_date fields (and any budget or pacing related fields) on the main insertion order level set to null (default setting).
    • Only associate seamless line items with seamless insertion orders. For instructions on how to create seamless line items, see Line Item Service - ALI.

  • To create a Legacy (non-seamless) insertion order, you must:

    • Use the budget and pacing related fields and the start_date and end_date fields on the main insertion order object to specify the dates during which the insertion order should run, what budget is available to it during those dates, and how the spending of the budget should be paced.
    • Ensure the budget_intervals field is set to null.
    • Only associate non-seamless line items with non-seamless insertion orders. For instructions on how to create non-seamless line items, see Line Item Service.

Important

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

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

Note

Insertion Orders for Guaranteed Delivery Augmented Line Items (GDALI)

For an insertion order to be associated with a guaranteed delivery augmented line item (GDALI), the insertion order must:

  • Be a Seamless Insertion Order (legacy insertion orders are not compatible).
  • Have budget_type set to "flexible" or "impression".
  • Not contain more than one budget_intervals array.
  • Have unlimited budget (set via the budget_intervals array).

Insertion orders not matching the above may only be associated to non-guaranteed line items. The above settings are also required for programmatic guaranteed line items (PGLI). An insertion order with the above settings may also be associated to non-guaranteed line items.

Associating a profile_id (e.g., frequency capping or setting additional targeting) on the insertion order object may result in unexpected forecasting or delivery for PGLIs and GDALIs. It is recommended not to use profile_id for insertion orders intended for the use with GDALIs.

REST API

HTTP Method Endpoint Description
POST https://api.appnexus.com/insertion-order?advertiser_id=ADVERTISER_ID
(insertion order JSON)		 Add a new insertion order.
PUT https://api.appnexus.com/insertion-order?id=INSERTIONORDER_ID&advertiser_id=ADVERTISER_ID
(insertion order JSON)		 Modify an existing insertion order.
GET https://api.appnexus.com/insertion-order?advertiser_id=ADVERTISER_ID View all of the insertion orders for one of your advertisers.
DELETE https://api.appnexus.com/insertion-order?id=INSERTIONORDER_ID&advertiser_id=ADVERTISER_ID

Important: Deleting an insertion order does not necessarily mean that associated line items will be deleted as the relationship between an insertion order and line item can be many to many. Also, deletion of an insertion order results in deletion of the associated budget intervals.		 Delete an insertion order.
GET https://api.appnexus.com/insertion-order?id=INSERTIONORDER_ID View a specific insertion order for one of your advertisers.
GET https://api.appnexus.com/insertion-order?id=1,2,3 View multiple insertion orders by ID using a comma-separated list.
GET https://api.appnexus.com/insertion-order?search=SEARCH_TERM Search for insertion orders with IDs or names containing certain characters.
GET https://api.appnexus.com/insertion-order/meta Find out which fields you can filter and sort by.

JSON fields

Field Type Description
id int The ID of the insertion order.
Required On: PUT
name string The name of the insertion order. (Maximum of 255 characters.)
Required On: POST
code string The custom code for the insertion order. The code may only contain alphanumeric characters, periods, underscores or dashes. The code you enter is not case-sensitive (upper- and lower-case characters are treated the same). No 2 objects at the same level (e.g., line items) can use the same code per advertiser. For example, 2 lines items cannot both use code "XYZ", but a single line item and its child campaign can.

Note: There may also be a custom code per budget interval.

For more details, see the Budget Intervals array below.
Default: null
state enum The state of the insertion order.
Possible values: "active" or "inactive".
Default: "active"
advertiser_id int The ID of the advertiser.
Required On: POST
start_date timestamp The start date of the non-seamless insertion order. If you are creating a seamless insertion order, do not set this field.
Default: null (immediately)
end_date timestamp The end date of the non-seamless insertion order. If you are creating a seamless insertion order, do not set this field.
Default: null (indefinitely)
remaining_days int The number of days between today and the end_date for the insertion order.

Note: This will be null if the start_date is in the future or if either the start_date or end_date is not set.

Read Only.
total_days int The number of days between the start_date and end_date for the insertion order.

Note: This will be null if either the start_date or end_date is not set.

Read Only.
last_modified timestamp The time of the last modification to this campaign.
Read Only.
timezone string The timezone by which budget and spend are counted. For a list of acceptable timezone values, see API Timezones.

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

Default: "EST5EDT" or the advertiser's timezone.
currency string The currency assigned to the insertion order. For a full list of available currencies, use the read-only Currency Service.

Note: Once the insertion order has been created, the currency cannot be changed.

Default: Default currency of the advertiser.
comments string Comments about the insertion order.
billing_code string The billing code for the insertion order. This will only appear on invoices that are insertion order-specific (e.g., if you receive an invoice per insertion order). For details on invoices, see "Understanding Your Invoice" in the Finance documentation.
Default: null
line_items array of objects The line items which are associated with the insertion order. For more information, see Line Items below.

Note: Seamless insertion orders may only be associated with seamless line items. Non-seamless insertions orders may only be associated with non-seamless line items.
labels array of objects The labels assigned to the insertion order. See Labels below.
broker_fees array of objects Warning: For augmented line items (ALIs):
Broker fees are deprecated for augmented line items. Create partner fees and apply them to the line item using the Partner Fee Service.
For standard line items:
- Broker fees created on an insertion order only apply to standard line items. If you also use augmented line items, you will need to create and apply partner fees to ALIs using the Partner Fee Service.
- Broker fees at the line item level override broker fees at the insertion order level.

The commissions that the network must pass to brokers when serving an ad. These commissions are deducted from the booked revenue (the amount the network receives from the advertiser) and are typically for brokering a relationship with the advertiser. They can either be a percentage of the revenue or a flat CPM. For more details, see Broker Fees below.
budget_intervals array of objects Note: This array is only relevant to and required for seamless insertion orders (if the insertion order is non-seamless, leave this field set to null).

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

Note:
If you use budget_intervals, the following fields should not be used on the top level insertion order object:
- lifetime_pacing
- lifetime_budget
- lifetime_budget_imps
- enable_pacing
- lifetime_pacing_span
- allow_safety_pacing
- daily_budget
- daily_budget_imps
- lifetime_pacing_pct
budget_type enum The budget type of the insertion order.
Values may be 'revenue', 'impression', or 'flexible'.
- If this field is set to 'impression' then both the lifetime_budget and daily_budget fields must be set to null.
- If this field is set to 'revenue' then both the lifetime_budget_imps and daily_budget_imps fields must be set to null.
- This field must be set when all four budget fields in the budget_intervals array (lifetime_budget, lifetime_budget_imps, daily_budget, and daily_budget_imps) have been set to null.
- If this field is set to 'flexible' then the budget_intervals array can only have one interval and all four budget fields in the budget_intervals array (lifetime_budget, lifetime_budget_imps, daily_budget, and daily_budget_imps) must be set to null.
lifetime_pacing boolean If true, the non-seamless insertion order will attempt to spend its overall lifetime budget evenly over the insertion order flight dates. If true:
- You must establish a lifetime_budget or lifetime_budget_imps.
- You must establish a start_date and end_date.
- You cannot set a daily_budget.
- You cannot set enable_pacing to false.

Note: Only applicable to non-seamless insertion orders.

Default: null
lifetime_budget double The lifetime budget in revenue. The revenue currency is defined by the currency field.

Note:
Only applicable to non-seamless insertion orders.

Default: null (unlimited)
lifetime_budget_imps int The lifetime budget in impressions.

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

Default: null (unlimited)
enable_pacing boolean If true, then spending will be paced over the course of the day. Only applicable if there is a daily_budget.

Note: Only applicable to non-seamless insertion orders.
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.

Note: Only applicable to non-seamless insertion orders.

Default: null (3 days)
daily_budget double The daily budget in revenue. The revenue currency is defined by the currency field.

Note: If you add line items to this insertion order, any impressions associated to those line items when they are added to the insertion order are NOT counted under the lifetime budget of the insertion order. Only impressions that occur while the line item is a child of the insertion order are counted. Only applicable to non-seamless insertion orders.

Default: null (unlimited)
daily_budget_imps int The daily budget in impressions.

Note:
Only applicable to non-seamless insertion orders.

Default: null (unlimited)
lifetime_pacing_pct double A double integer between (and including) 50 and 150, used to set pacing throughout the insertion order's lifetime. Possible values can be any double between 50 and 150 on the following scale:
- 50: Pace behind schedule.
- 100: Pace evenly.
- 150: Pace ahead of schedule.

Note: Only applicable to non-seamless insertion orders.
Alpha-Beta Notice
This field or feature is part of functionality currently in either Alpha or Beta phase. It is therefore subject to change.

Default: 100
profile_id int Specifies the ID of the profile attached to the seamless insertion order (i.e., must use budget_intervals). A profile can be used to define how inventory is targeted and/or how frequency capping is enforced (For details, see Profile Service). A profile can also be set at the advertiser, line item, campaign, and creative levels. The most restrictive setting always takes precedence.
stats object The stats object has been deprecated (as of October 17, 2016). Use the Report Service to obtain statistical information instead.
object_stats object The number of total, active, and inactive line items under the insertion order. To include this object in a GET response, pass object_stats=true in the query string.
Read Only.
viewability_standard_provider string This field determines what standard to measure viewability against. For example, iab.

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

Default: 'iab'
is_running_political_ads boolean Declares whether or not this insertion order contains political advertising (defined as advertising related to an election, ballot initiative, or political candidate, in the United States). If true, the political_content object is editable. If true, and if the insertion order targets a state with additional political reporting requirements, many fields in political_content object are required. For more information on state requirements, see Political Advertising Policy Implementation. For more information on the political_content object, see Political Content below.
is_running_political_ads must be set to true on the advertiser to be set to true on the insertion order. For more information, see the Advertiser Service.
Default: 0 false
political_content object Information about political advertising conducted with this insertion order. Political advertising must be enabled on the advertiser and on this insertion order for this object to be editable. (That is, the field is_running_political_ads must be true on both the advertiser and the insertion order.)
For more information about this object, see Political Content below.

Line items

Each object in the line_items array contains the following fields.

Field Type Description
id int The numeric ID associated with this line item.
Required On: POST or PUT.
line_item_type enum The type associated with the child line item. Possible values are:
- "standard_v1": Denotes that the child line item is a standard line item.
- "standard_v2": Denotes that the child line item is an augmented line item.
- "guaranteed": Denotes that the child line item is a guaranteed line item.
- "performance": This line item type has been deprecated.
name string The name of the line item.
code string If you have chosen to associate an optional identifying name (a "code") with this line item, it will show up here.
state string Line items can be "active" or "inactive".
end_date date The date when line items stop serving.
start_date date The date when line items start serving.
timezone string The timezone with which the line item is set to. This will affect the start_date and end_date.

Labels

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

Field Type Description
value string (100) The value assigned to the label. For example, for the "Sales Rep" label, this could be a name such as "Michael Sellers".
id int The ID of the label.
Required On: POST or PUT.
name enum The name of the label. Possible values:
- "Trafficker"
- "Sales Rep"
- "Campaign Type"

Broker fees

Warning

For augmented line items (ALIs):

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

For standard line items:

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

Note

The decimal position support for the broker fees in UI is for 1 place after the decimal. For example, if you set 16.67% as a broker fee in the Commissions section, after saving, the value would round off to 16.7%. However, there is no restriction on number of places after decimal if the Insertion Order service API is used to create the broker fee.

Each object in the broker_fees array contains the following fields.

Field Type Description
broker_id int The ID of the broker.
payment_type enum Type of payment to the broker. Possible values:
- "cpm"
- "revshare"
value double The value of the payment, based on the payment type.
description string (255) The free-form description of the broker fee entry.

Budget intervals

Note

This array is only used for seamless insertion orders.

Consider the following when using the budget_interval array:

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

Each object in the budget_intervals array contains the following fields.

Field Type Description
id int The ID of the budget interval.
start_date timestamp The start date of the budget interval. Format must be YYYY-MM-DD hh:mm:ss (hh:mm:ss must be set to 00).
end_date timestamp The end date of the budget interval. Format must be YYYY-MM-DD hh:mm:ss (hh:mm:ss must be set to 23:59:59). If this field is set to null, then the insertion order's budget interval will run indefinitely. If you set this field to 'null':
- There may not be more than one object in the budget_intervals array (i.e., maximum of 1 budget interval).
- The lifetime_pacing field must set to "false".
- The "daily_budget" field must be set to null.
timezone string The timezone by which budget and spend are counted. For a list of acceptable timezone values, see API Timezones. The default value is "EST5EDT" or the advertiser's timezone.
code string The custom code for the budget interval. The code may only contain alphanumeric characters, periods, underscores or dashes. The code you enter is not case-sensitive (upper- and lower-case characters are treated the same).
lifetime_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 within this array, whichever budget is exhausted first will cause spending to stop. Best practice is to only set one of these fields.
lifetime_budget_imps int The lifetime budget in impressions for the budget interval.
Note: If you add line items to this insertion order, any spend already associated with those line items before they are added to the insertion order is not counted against the lifetime budget of the insertion order. Only spend that occurs while the line item is a child of the insertion order is counted.

This field defaults to null (unlimited).

Note:
If you also set the lifetime_budget field within this array, whichever budget is exhausted first will cause spending to stop. Best practice is to only set one of these fields.
lifetime_pacing boolean If true, the insertion order will attempt to pace the lifetime budget evenly over the budget interval. If true:
- You must establish a lifetime_budget or lifetime_budget_imps.
- You must establish a start_date and end_date.
You cannot set a daily_budget.
- You cannot set enable_pacing to false.
daily_budget double Note:
This field defaults to null (unlimited). Instead, use the line item to set this value.
If you also set the daily_budget_imps field within this array, whichever budget is exhausted first will cause spending to stop. Best practice is to only set one of these fields.
daily_budget_imps int Note: This field defaults to null (unlimited). Instead, use the line item to set this value.
If you also set the daily_budget field within this array, whichever budget is exhausted first will cause spending to stop. Best practice is to only set one of these fields.
enable_pacing boolean If true, then spending will be paced over the course of the day. Only applicable if there is a daily_budget.
lifetime_pacing_pct double Note:
Set this field to 100 (the default) and then use the line item to set lifetime pacing.

A double integer between (and including) 50 and 150, used to set pacing throughout a budget interval. Possible values can be any double between 50 and 150 on the following scale:
- 50: Pace behind schedule.
- 100: Pace evenly.
- 150: Pace ahead of schedule.

Political content

This array will only be editable if:

  • is_running_political_ads is true on the Advertiser Service.
  • is_running_political_ads is true on the insertion order.

These fields must be filled out if you are using this insertion order for advertising related to an election, ballot initiative, or political candidate at the local or state level in the United States, or for advertising related to federal election or political candidate in Washington State. They are not required for political advertising at the federal level in other states.

Warning

We do not validate the required fields to make sure they're present when you create an insertion order, but your creative for state or local political advertising or federal advertising that targets Washington State will not serve if the fields are not filled out. Any update to the political_content object should include all required fields or ad serving may be disrupted.

Field Type Description
billing_name string The name of the person or organization that is purchasing ads on Xandr. This will be automatically filled out with the name of the Xandr member.
Read Only.
billing_address_1 string(255) The street address for the person or organization that is purchasing ads on Xandr.
Enter the contact details for the person or team who can best answer any questions about political advertising on this insertion order.
Required.
billing_address_2 string(255) Optional additional line for the billing address for the person or organization that is purchasing ads on Xandr.
billing_city string(100) City of the billing address for the person or organization that is purchasing ads on Xandr.
Required.
billing_region string(50) State or region of the billing address for the person or organization that is purchasing ads on Xandr.
Required.
billing_postal_code string(50) ZIP or postal code of the billing address for the person or organization that is purchasing ads on Xandr.
Required.
billing_country string(50) Country of the billing address for the person or organization that is purchasing ads on Xandr.
Required.
billing_phone_code string(10) Country code for the phone number for the person or organization that is purchasing ads on Xandr.
Required.
billing_phone string(50) Contact phone number for the person or organization that is purchasing ads on Xandr.
Required.
us_fecid string(50) ID number assigned by the U.S. Federal Election Committee.
organization_name string(100) Name of the person, group, organization, or business that is advertising (the client that is paying you). For example, a candidate, an agency, or a political consultant.
Required.
organization_address_1 string(255) Address of the person, group, organization, or business that is advertising. For example, a candidate, an agency, or a political consultant.
Required.
organization_address_2 string(255) Optional second line for the address of the person, group, organization, or business that is advertising.
organization_city string(100) City in the address of the person, group, organization, or business that is advertising.
Required.
organization_region string(50) State or region in the address of the person, group, organization, or business that is advertising.
Required.
organization_postal_code string(50) ZIP or postal code of the person, group, organization, or business that is advertising.
Required.
organization_country string(50) Country of the person, group, organization, or business that is advertising.
Required.
organization_phone_code string(10) Country code for the phone number of the person, group, organization, or business that is advertising.
Required.
organization_phone string(50) Phone number of the person, group, organization, or business that is advertising.
Required.
treasurer_name string(100) Treasurer for the committee purchasing the ads, or the individual whose role would most closely fit that of a treasurer.
Required.
payment_method_type enum(1) How the political organization pays you. Options are:
- "Direct Debit"
- "Check"
- "Credit Card"
- "Other". If this is selected, payment_method_other is required.
Required.
political_objective string(255) The candidate or ballot initiative that is supported or opposed.
This maps to the Subject of Ads field in the UI.
Required.
payment_method_other string(50) If "4" (Other) is selected for payment_method_type. Details of how you are being paid for political advertising.
Required.
is_independent_expenditure_committee Boolean Specifies whether any ads are being paid for by an independent expenditure committee: That is, a third party that spends money on political communications that expressly advocate the election or defeat of a clearly identified candidate and does not coordinate with a candidate, a candidate’s authorized committee, or an agent of the candidate.
Required.
registration_form array Required for NY and NJ when is_independent_expenditure_committee is true. New York State and New Jersey require copies of state registration forms from independent expenditure committees making purchases. Creatives won’t serve in New York State or New Jersey until the form is uploaded. Forms must be uploaded with the Registration Form Service before their location can be specified in this array.
The array must be in the format:
{"file_path": "PATH_AND_FILE_NAME_OF_THE_UPLOADED_FILE"}
is_ineligible Boolean Notifies you whether all the required fields in the political_content array have been filled out (excluding registration_form) for political advertising at the state or local level. If the value is true, creatives will not serve. The value is recalculated whenever the insertion order is updated.

Note:
If is_ineligible is false, creatives may still be prohibited from serving, based on other factors such as whether the creative has passed audit or whether a registration form has been uploaded for ad buys in states which require it.

For more information on creative auditing, see "Creative Troubleshooting and FAQ" in the UI documentation.
Read Only.
government_level enum If is_running_political_ads is true. Permitted values are:
- state or local
- federal
- both (the default)
Required.
is_accuracy_acknowledged Boolean Specifies that the Xandr member has certified that the political_content information provided is accurate and up-to-date and that Xandr is relying on the accuracy of the information provided. If set to 0 (the default), creatives will not be allowed to serve.
Required.

Stats

Warning

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

Examples

Add a new seamless insertion order with budget intervals

$ cat insertion-order.json
{
    "insertion-order": {
        "name": "My Insertion Order LH_EP",
        "budget_intervals": [

            {
                "start_date": "2030-10-10 00:00:00",
                "end_date": "2030-10-12 23:59:59",
                "daily_budget": null,
                "daily_budget_imps": 10,
                "enable_pacing": true,
                "lifetime_budget": null,
                "lifetime_budget_imps": 980,
                "lifetime_pacing": false
            },
            {
                "start_date": "2030-10-13 00:00:00",
                "end_date": "2030-10-18 23:59:59",
                "daily_budget": null,
                "daily_budget_imps": 10,
                "enable_pacing": true,
                "lifetime_budget": null,
                "lifetime_budget_imps": 6,
                "lifetime_pacing": false
            }
        ]
    }
}
$ curl -b cookies -X POST -d @insertion-order.json "https://api.appnexus.com/insertion-order?advertiser_id=11'

{
   "response": {
    "status": "OK",
    "count": 1,
    "start_element": 0,
    "num_elements": 100,
    "insertion-orders": [
        {
            "id": 45797,
            "name": "MyInsertionOrderLH_EP",
            "code": null,
            "state": "active",
            "advertiser_id": 64,
            "start_date": null,
            "end_date": null,
            "last_modified": "2015-03-1718: 41: 57",
            "timezone": "EST5EDT",
            "currency": "USD",
            "budget_type": null,            
            "comments": null,
            "billing_code": null,
            "line_items": null,
            "labels": null,
            "broker_fees": null,
            "budget_intervals": [
                {
                    "id": 684,
                    "start_date": "2030-10-10 00:00:00",
                    "end_date": "2030-10-12 23:59:59",
                    "parent_interval_id": null,
                    "lifetime_budget": null,
                    "lifetime_budget_imps": 980,
                    "lifetime_pacing": false,
                    "enable_pacing": false,
                    "daily_budget_imps": 10,
                    "daily_budget": null
                },
                {
                    "id": 685,
                    "start_date": "2030-10-13 00:00:00",
                    "end_date": "2030-10-18 23:59:59",
                    "parent_interval_id": null,
                    "lifetime_budget": null,
                    "lifetime_budget_imps": 6,
                    "lifetime_pacing": false,
                    "enable_pacing": false,
                    "daily_budget_imps": 10,
                    "daily_budget": null
                }
            ],
            "lifetime_pacing": null,
            "lifetime_budget": null,
            "lifetime_budget_imps": null,
            "enable_pacing": null,
            "lifetime_pacing_span": null,
            "allow_safety_pacing": null,
            "daily_budget": null,
            "daily_budget_imps": null
            }
        ]
    }
}

Add a new seamless insertion order with flexible budget type

$ cat insertion-order.json
{
    "insertion-order": {
        "name": "Test-Seamless-IO-GDALI",
        "advertiser_id": "33514",
        "timezone": "UTC",
        "budget_type": "flexible",
        "budget_intervals": [{
            "start_date": "2022-11-01 00:00:00",
            "timezone": "UTC"
        }],
        "currency": "USD"
    }
}



curl -b cookies -X POST -d @insertion-order.json "https://api.appnexus.com/insertion-order?advertiser_id=33514&member_id=958"


{
    "response": {
        "status": "OK",
        "count": 1,
        "id": 6784364,
        "start_element": 0,
        "num_elements": 100,
        "insertion-order": {
            "id": 6784364,
            "name": "Test-Seamless-IO-GDALI",
            "code": null,
            "state": "active",
            "advertiser_id": 33514,
            "profile_id": null,
            "member_id": 958,
            "start_date": null,
            "end_date": null,
            "remaining_days": null,
            "total_days": null,
            "last_modified": "2022-01-26 20:00:29",
            "timezone": "UTC",
            "currency": "USD",
            "comments": null,
            "budget_type": "flexible",
            "billing_code": null,
            "viewability_standard_provider": "iab",
            "is_running_political_ads": false,
            "line_items": null,
            "labels": null,
            "broker_fees": null,
            "budget_intervals": [{
                "id": 16134020,
                "object_id": 6784364,
                "object_type": "insertion_order",
                "start_date": "2022-11-01 00:00:00",
                "end_date": null,
                "timezone": "UTC",
                "code": null,
                "lifetime_budget": null,
                "lifetime_budget_imps": null,
                "daily_budget_imps": null,
                "daily_budget": null,
                "enable_pacing": false,
                "lifetime_pacing": false,
                "lifetime_pacing_pct": null,
                "daily_budget_imps_opt": null,
                "daily_budget_opt": null
            }],
            "tpas_details": null,
            "political_content": null,
            "lifetime_pacing": null,
            "lifetime_budget": null,
            "lifetime_budget_imps": null,
            "enable_pacing": null,
            "lifetime_pacing_span": null,
            "allow_safety_pacing": null,
            "daily_budget": null,
            "daily_budget_imps": null,
            "lifetime_pacing_pct": null
        }
    }
}

Add a new non-seamless insertion order

$ cat insertion-order.json

{
    "insertion-order":{
        "name":"My Insertion Order"
    }
}

$ curl -b cookies -X POST -d @insertion-order.json "https://api.appnexus.com/insertion-order?advertiser_id=11"
 
{
    "response":{
        "status":"OK",
        "id":2
    }
}

View all insertion orders for advertiser 11

$ curl -b cookies "https://api.appnexus.com/insertion-order?advertiser_id=11"

    "response":{
        "status":"OK",
        "count":2,
        "start_element":0,
        "num_elements":100,
        "insertion-orders":[
            {
                "id":1,
                "name":"TEST CPM IO",
                "code":null,
                "billing_code":"3az56",
                "state":"active",
                "advertiser_id":11,
                "start_date":"2010-07-01 00:00:00",
                "end_date":"2010-09-01 23:59:59",
                "last_modified":"2010-08-02 23:44:14",
                "timezone":"EST5EDT",
                "currency":"USD",
                "budget_type": null,                
                "comments":null,
                "users":null,
                "line_items":[
                    {
                        "id":5588,
                        "line_item_type": "standard_v1",
                        "name":"Test IO Line Item CPM",
                        "code":null,
                        "state":"active",
                        "start_date":null,
                        "end_date":null,
                        "timezone":"EST5EDT"
                    }
                ],
                "labels":null,
                "broker_fees":null,
                "lifetime_budget":null,
                "lifetime_budget_imps":1000,
                "daily_budget":null,
                "daily_budget_imps":100,
                "enable_pacing":true,
                "lifetime_pacing":false,
                "lifetime_pacing_span":null,
                "allow_safety_pacing":true
            },
            {
                "id":2,
                "name":"TEST CPM IO - Expired Flight Dates",
                "code":null,
                "billing_code":null,
                "state":"active",
                "advertiser_id":2396,
                "start_date":"2010-06-01 00:00:00",
                "end_date":"2010-06-30 23:59:59",
                "last_modified":"2010-07-30 01:29:28",
                "timezone":"EST5EDT",
                "currency":"USD",
                "budget_type": null,                
                "comments":null,
                "users":null,
                "line_items":[
                    {
                        "id":5588,
                        "line_item_type": "standard_v1",
                        "name":"Test IO Line Item CPM",
                        "code":null,
                        "state":"active",
                        "start_date":null,
                        "end_date":null,
                        "timezone":"EST5EDT"
                    }
                ],
                "labels":null,
                "broker_fees":null,
                "lifetime_budget":null,
                "lifetime_budget_imps":1000,
                "daily_budget":null,
                "daily_budget_imps":100,
                "enable_pacing":true,
                "lifetime_pacing":false,
                "lifetime_pacing_span":null,
                "allow_safety_pacing":true
            }
        ]
}

Delete a budget interval (on a seamless insertion order)

Note

The deletion of budget intervals on an insertion order will affect the underlying line items differently, depending on their type:

  • For non-ALI (augmented) line items: The deletion of budget intervals on the parent insertion order will automatically delete the relevant budget interval on the line item(s). Do not attempt to delete budget intervals from the line item object. Always use the parent insertion order to delete a budget interval.
  • For ALI line items: You cannot delete a budget interval on a parent insertion until you have first removed it from all of the underlying augmented line items associated with the insertion order. Since augmented line items may have more than one budget interval within a given budget interval on the parent insertion order, be sure to remove all budget intervals on the augmented line line item that fall within the insertion order budget interval you intend to remove. Once the budget interval(s) has been removed from the augmented line items, it can be removed from the insertion order.
//To delete a budget interval, both the "start_date" and "end_date" fields must be set to null.
$ cat delete-budget-interval
{
  "insertion-order": {
    "budget_intervals": [
      {
        "id": 79970,
        "start_date": null,
        "end_date": null
      }
    ]
  }
}
$ curl -b cookies -X PUT -d @delete-budget-interval "https://api.appnexus.com/insertion-order?id=357903"
{
  "response": {
    "status": "OK",
    "count": 1,
    "id": "357903",
    "start_element": 0,
    "num_elements": 100,
    "insertion-order": {
      "id": 357903,
      "name": "Seamless Insertion Order",
      "code": null,
      "state": "active",
      "advertiser_id": 1133550,
      "start_date": null,
      "end_date": null,
      "remaining_days": null,
      "total_days": null,
      "last_modified": "2016-07-26 21:33:34",
      "timezone": "America/Argentina/Buenos_Aires",
      "currency": "USD",
      "budget_type": null,
      "comments": null,
      "billing_code": null,
      "line_items": [
        {
          "id": 3188266,
          "line_item_type": "standard_v1",
          "name": "Seamless Line Item",
          "code": null,
          "state": "active",
          "start_date": null,
          "end_date": null,
          "timezone": "America/Argentina/Buenos_Aires"
        }
      ],
      "spend_protection_pixels": null,
      "labels": null,
      "broker_fees": null,
      "budget_intervals": [
        {
          "id": 79969,
          "object_id": 357903,
          "object_type": "insertion_order",
          "start_date": "2016-08-01 00:00:00",
          "end_date": "2016-08-31 23:59:59",
          "code": null,
          "timezone": "America/Argentina/Buenos_Aires",
          "lifetime_budget": 100,
          "lifetime_budget_imps": null,
          "lifetime_pacing": false,
          "enable_pacing": true,
          "daily_budget_imps": null,
          "daily_budget": null
        }
      ],
      "tpas_details": null,
      "lifetime_pacing": null,
      "lifetime_budget": null,
      "lifetime_budget_imps": null,
      "enable_pacing": null,
      "lifetime_pacing_span": null,
      "allow_safety_pacing": null,
      "daily_budget": null,
      "daily_budget_imps": null,
      "lifetime_pacing_pct": null
    },
    "dbg_info": {
      ...
    }
  }
}

Modify a budget interval (on a seamless insertion order)

$ cat modify-budget-interval
{

  "insertion-order": {
    "budget_intervals": [
      {
        "id": 79969,
        "lifetime_budget": 100
      }
    ]
  }
}
$ curl -b cookies -X PUT -d @modify-budget-interval "https://api.appnexus.com/insertion-order?id=357903"
{
  "response": {
    "status": "OK",
    "count": 1,
    "id": "357903",
    "start_element": 0,
    "num_elements": 100,
    "insertion-order": {
      "id": 357903,
      "name": "Seamless Insertion Order",
      "code": null,
      "state": "active",
      "advertiser_id": 1133550,
      "start_date": null,
      "end_date": null,
      "remaining_days": null,
      "total_days": null,
      "last_modified": "2016-07-29 17:26:26",
      "timezone": "America/Argentina/Buenos_Aires",
      "currency": "USD",
      "budget_type": null,
      "comments": null,
      "billing_code": null,
      "line_items": null,
      "spend_protection_pixels": null,
      "labels": null,
      "broker_fees": null,
      "budget_intervals": [
        {
          "id": 79969,
          "object_id": 357903,
          "object_type": "insertion_order",
          "start_date": "2016-08-01 00:00:00",
          "end_date": "2016-08-31 23:59:59",
          "code": null,          
          "timezone": "America/Argentina/Buenos_Aires",
          "lifetime_budget": 100,
          "lifetime_budget_imps": null,
          "lifetime_pacing": false,
          "enable_pacing": true,
          "daily_budget_imps": null,
          "daily_budget": null
        }
      ],
      "tpas_details": null,
      "lifetime_pacing": null,
      "lifetime_budget": null,
      "lifetime_budget_imps": null,
      "enable_pacing": null,
      "lifetime_pacing_span": null,
      "allow_safety_pacing": null,
      "daily_budget": null,
      "daily_budget_imps": null,
      "lifetime_pacing_pct": null
    },
    "dbg_info": {
      ...
    }
  }
}

Delete an insertion order

curl -b cookies -X DELETE "https://api.appnexus.com/insertion-order?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"}
            }
    }
}