InsertionOrder Data Object - Customer Billing

An insertion order is a contract that establishes the maximum amount you will spend on your account over a specified period of time. If you have monthly invoice billing set up for your account, you need to have an active insertion order for your ads to be eligible for delivery. You still control your spend using your campaign budget, and you will only be charged for what you accrue. For example, if you had a month-long insertion order for $5,000 and accrued only $4,500 in charges over the billing period, then we will only deduct $4,500 from your insertion order budget.

Warning

The insertion order budget only applies to ad spend, which is an important distinction if your business is in a country/region where online services are taxed. If you have a strict budget limit, you may need to account for taxes in your insertion order budget. To learn more about tax requirements in your business location, see the Tax or VAT information help article.

Most elements of this object can only be set before the insertion order becomes approved i.e., if the Status is set to PendingUserReview. In that case you can either make new changes or approve or decline the insertion order via elements of this object. Once the insertion order Status is Active, Exhausted, Expired, or NotStarted, then you can either make new changes or approve or decline the current pending changes via the PendingChanges element. If the insertion order Status is Canceled or Declined then you cannot update the insertion order.

Note

The SearchInsertionOrders operation will return up to 24 insertion orders per recurring series.

You can retrieve but with very few exceptions cannot add or update an insertion order series via the Bing Ads API. Use the IsInSeries element (available starting with Bing Ads API Version 13) to determine whether the insertion order is in a recurring series.

  • If you attempt to update the StartDate or EndDate of an insertion order that is part of a recurring series the API will return an error.
  • If you update the Status of an insertion order that is part of a recurring series, the status update will be applied to all insertion orders in the series.

To manage recurring insertion orders in the Microsoft Advertising web application, see the How do I create and edit an insertion order? help article.

Syntax

<xs:complexType name="InsertionOrder" xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:sequence>
    <xs:element minOccurs="0" name="AccountId" type="xs:long" />
    <xs:element minOccurs="0" name="BalanceAmount" nillable="true" type="xs:double" />
    <xs:element minOccurs="0" name="BookingCountryCode" nillable="true" type="xs:string" />
    <xs:element minOccurs="0" name="Comment" nillable="true" type="xs:string" />
    <xs:element minOccurs="0" name="EndDate" nillable="true" type="xs:dateTime" />
    <xs:element minOccurs="0" name="Id" nillable="true" type="xs:long" />
    <xs:element minOccurs="0" name="LastModifiedByUserId" nillable="true" type="xs:long" />
    <xs:element minOccurs="0" name="LastModifiedTime" nillable="true" type="xs:dateTime" />
    <xs:element minOccurs="0" name="NotificationThreshold" nillable="true" type="xs:double" />
    <xs:element minOccurs="0" name="ReferenceId" nillable="true" type="xs:long" />
    <xs:element minOccurs="0" name="SpendCapAmount" nillable="true" type="xs:double" />
    <xs:element minOccurs="0" name="StartDate" nillable="true" type="xs:dateTime" />
    <xs:element minOccurs="0" name="Name" nillable="true" type="xs:string" />
    <xs:element minOccurs="0" name="Status" nillable="true" type="tns:InsertionOrderStatus" />
    <xs:element minOccurs="0" name="PurchaseOrder" nillable="true" type="xs:string" />
    <xs:element minOccurs="0" name="PendingChanges" nillable="true" type="tns:InsertionOrderPendingChanges" />
  </xs:sequence>
</xs:complexType>

Elements

Element Description Data Type
AccountId The identifier of the account to which the insertion order applies.

You cannot update the account identifier after you create the insertion order.

Add: Required
Update: Read-only
long
BalanceAmount The running balance of the insertion order. The running balance value is initially the same as the spending limit, and then decreases each time an ad in the account is served.

Add: Read-only
Update: Read-only
double
BookingCountryCode A code that identifies the country/region in which the account operates. For a list of country code values, see Geographical Location Codes.

You cannot update the country code after the insertion order becomes active.

Add: Required
Update: Read-only
string
Comment A description of the insertion order. The description is limited to 100 characters.

Add: Optional
Update: Optional
string
EndDate The date that the insertion order expires. The end date must be later than the start date.

The date is stored in Coordinated Universal Time (UTC). Only the month, day, and year of the specified string are used. If you specify the hour, minutes, and seconds of a date they will be ignored.

For information about the format of the date and time, see the dateTime entry in Primitive XML Data Types.

Add: Required
Update: Optional. If you attempt to update the StartDate or EndDate of an insertion order that is part of a recurring series the API will return an error.
dateTime
Id A system generated identifier that identifies the insertion order.

Add: Read-only
Update: Read-only
long
LastModifiedByUserId An identifier of the last user to update the insertion order.

Add: Read-only
Update: Read-only
long
LastModifiedTime The date and time that the insertion order was last updated.

The date is stored in Coordinated Universal Time (UTC).

For information about the format of the date and time, see the dateTime entry in Primitive XML Data Types.

Add: Read-only
Update: Read-only
dateTime
Name The friendly name that can be used to reference this insertion order.

The name can contain a maximum of 100 characters.

The name does not need to be unique compared to other insertion orders for the customer.

Add: Optional
Update: Optional
string
NotificationThreshold A percentage of the budget that has been spent. Specify the percentage as a value from 0 to 100. Notification is sent when the threshold is reached. For example, if you set the threshold to 70, the Billing service sends notification when you have spent 70 percent of the budget.

If you do not want to receive notification, set to NULL.

Reserved for internal use.

Add: Optional
Update: Optional
double
PendingChanges Can be used to manage changes for an approved insertion order with status set to either Active, Exhausted, Expired, or NotStarted.

Add: Read-only
Update: Optional
InsertionOrderPendingChanges
PurchaseOrder A purchase order value that can be used to reference this insertion order in monthly invoices. This value will be printed as the purchase order in the monthly invoices.

The purchase order can contain a maximum of 50 characters.

Add: Optional
Update: Optional
string
ReferenceId Internal use only.

Add: Optional
Update: Optional
long
SpendCapAmount The budget for this insertion order. The budget is a hard limit. When the account reaches this limit and there is not another insertion order available, the account's lifecycle status value is set to Pause.

Add: Required
Update: Optional
double
StartDate The date that the insertion order can begin accruing charges. The start date must be later than the current date.

The date is stored in Coordinated Universal Time (UTC). Only the month, day, and year of the specified string are used. If you specify the hour, minutes, and seconds of a date they will be ignored.

For information about the format of the date and time, see the dateTime entry in Primitive XML Data Types.

Add: Required
Update: Optional. You can only update the start date via this element if the Status is PendingUserReview. If the start date has already passed, then you cannot change it.

If you attempt to update the StartDate or EndDate of an insertion order that is part of a recurring series the API will return an error.
dateTime
Status The status of the insertion order.

Add: Read-only. Insertion orders that you create are immediately set to Active, NotStarted, or Declined.
Update: Required to approve or decline an insertion order that is not yet approved, or cancel an insertion order that has already be approved. You can only approve or decline via this element if the current status is set to PendingUserReview. You can only cancel via this element if the current status is set to Active, Exhausted, or NotStarted. Once the insertion order status is Active, Exhausted, Expired, or NotStarted, then you can either make new changes or approve or decline the current pending changes via the PendingChanges element.

When you call UpdateInsertionOrder you can either set this Status element or modify other elements of this object, but you cannot change the status in parallel with other property updates.

If you update the Status of an insertion order that is part of a recurring series, the status update will be applied to all insertion orders in the series.
InsertionOrderStatus

Requirements

Service: CustomerBillingService.svc v12
Namespace: https://bingads.microsoft.com/Customer/v12/Entities

Used By

AddInsertionOrder
GetInsertionOrdersByAccount
SearchInsertionOrders
UpdateInsertionOrder