Edit

Share via

InsertionOrder Data Object - Customer Billing

  • Article

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 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="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:element minOccurs="0" name="AccountNumber" nillable="true" type="xs:string" />
    <xs:element minOccurs="0" name="BudgetRemaining" nillable="true" type="xs:double" />
    <xs:element minOccurs="0" name="BudgetSpent" nillable="true" type="xs:double" />
    <xs:element minOccurs="0" name="BudgetRemainingPercent" nillable="true" type="xs:double" />
    <xs:element minOccurs="0" name="BudgetSpentPercent" nillable="true" type="xs:double" />
    <xs:element minOccurs="0" name="SeriesName" nillable="true" type="xs:string" />
    <xs:element minOccurs="0" name="IsInSeries" nillable="true" type="xs:boolean" />
    <xs:element minOccurs="0" name="SeriesFrequencyType" nillable="true" type="xs:string" />
    <xs:element minOccurs="0" name="IsUnlimited" nillable="true" type="xs:boolean">
      <xs:annotation>
        <xs:appinfo>
          <DefaultValue EmitDefaultValue="false" xmlns="http://schemas.microsoft.com/2003/10/Serialization/" />
        </xs:appinfo>
      </xs:annotation>
    </xs:element>
    <xs:element minOccurs="0" name="IsEndless" nillable="true" type="xs:boolean">
      <xs:annotation>
        <xs:appinfo>
          <DefaultValue EmitDefaultValue="false" xmlns="http://schemas.microsoft.com/2003/10/Serialization/" />
        </xs:appinfo>
      </xs:annotation>
    </xs:element>
  </xs:sequence>
</xs:complexType>

Elements

The InsertionOrder object has the following elements: AccountId, AccountNumber, BookingCountryCode, BudgetRemaining, BudgetRemainingPercent, BudgetSpent, BudgetSpentPercent, Comment, EndDate, Id, IsEndless, IsInSeries, IsUnlimited, LastModifiedByUserId, LastModifiedTime, Name, NotificationThreshold, PendingChanges, PurchaseOrder, ReferenceId, SeriesFrequencyType, SeriesName, SpendCapAmount, StartDate, Status.

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
AccountNumber The system-generated account number that is used to identify the account in the Microsoft Advertising web application. The account number has the form xxxxxxxx, where xxxxxxxx is a series of any eight alphanumeric characters.

Add: Read-only
Update: Read-only		 string
BookingCountryCode Reserved for internal use.

Add: Required for some accounts; Optional for some accounts.
Update: Read-only		 string
BudgetRemaining The running balance of the insertion order.

The running balance value is initially the same as the SpendCapAmount, and then decreases each time an ad in the account is served.

This element is empty if the insertion order has unlimited budget.

Add: Read-only
Update: Read-only		 double
BudgetRemainingPercent The percent of budget remaining for the insertion order.

This value is calculated as BudgetRemaining / SpendCapAmount.

This element is empty if the insertion order has unlimited budget.

Add: Read-only
Update: Read-only		 double
BudgetSpent The remaining balance of the insertion order.

The remaining balance is initially 0 (zero), and then increases towards the SpendCapAmount each time an ad in the account is served.

This element is empty if the insertion order has unlimited budget.

Add: Read-only
Update: Read-only		 double
BudgetSpentPercent The percent of budget spent for the insertion order.

This value is calculated as BudgetSpent / SpendCapAmount.

This element is empty if the insertion order has unlimited budget.

Add: Read-only
Update: Read-only		 double
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.

Note: If the insertion order has no end date, EndDate is empty. Adding or updating unlimited insertion orders isn't supported. EndDate operates in read-only mode.

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 and Required		 long
IsEndless Determines whether the insertion order has no end date.

If the value is True, the insertion order will have no end date and the EndDate of this insertion order will be ignored.

Add: Optional
Update: Optional		 boolean
IsInSeries Determines whether the insertion order is in a recurring series.

If the value is True, the insertion order is part of 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.

Add: Read-only
Update: Read-only		 boolean
IsUnlimited Determines whether the insertion order has unlimited budget.

If the value is True, the insertion order will have unlimited budget and the SpendCapAmount of this insertion order will be ignored.

Add: Optional
Update: Optional		 boolean
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 Reserved for internal use only.

Add: Optional
Update: Optional		 long
SeriesFrequencyType Determines how an order recurs in the series.

The possible values are Monthly, BiMonthly, Quarterly, and Yearly.

Add: Read-only
Update: Read-only		 string
SeriesName The name of the recurring insertion order series.

The name can contain a maximum of 100 characters.

Even if the insertion order is later removed from the recurring series, this element will continue to reflect the name of the series it was created in.

Add: Read-only
Update: Read-only		 string
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.

This element is empty if the insertion order has unlimited budget. The budget is the maximum amount of money you want to spend for an insertion order. For insertion orders with unlimited budget, your budget is bounded by your credit limit. In that case each campaign's daily budget determines the maximum spend.

Note: Adding or updating unlimited insertion orders isn't supported. SpendCapAmount operates in read-only mode.

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 v13
Namespace: https://bingads.microsoft.com/Customer/v13/Entities

Used By

AddInsertionOrder
SearchInsertionOrders
UpdateInsertionOrder