插入Order 数据对象 - 客户计费

插入订单是一个合同，用于确定在指定时间段内在帐户上花费的最大金额。 如果你的帐户设置了每月发票计费，则需要有一个有效的插入订单，使广告符合投放条件。 你仍然使用市场活动预算控制支出，并且只会收取应计费用。 例如，如果你的一个月插入订单为 5,000 美元，但在计费周期内只累积了 4,500 美元的费用，则我们只将从你的插入订单预算中扣除 4,500 美元。

警告

插入订单预算仅适用于广告支出，如果你的业务位于联机服务征税的国家/地区，这是一个重要的区别。 如果你有严格的预算限制，可能需要在插入订单预算中考虑税款。 若要详细了解企业所在地的税务要求，请参阅 税务或增值税信息 帮助文章。

此对象的大多数元素只能在插入顺序获得批准之前设置，即，如果 Status 设置为 PendingUserReview。 在这种情况下，你可以进行新的更改，或者通过此对象的元素批准或拒绝插入顺序。 插入顺序 状态 为“活动”、“已用”、“已过期”或“NotStarted”后，即可进行新的更改，或者通过 PendingChanges 元素批准或拒绝当前挂起的更改。 如果插入订单 状态 为“已取消”或“已拒绝”，则无法更新插入订单。

注意

SearchInsertionOrders 操作将返回每个重复序列最多 24 个插入订单。

可以检索，但极少数例外，无法通过必应广告 API 添加或更新插入顺序系列。 使用 IsInSeries 元素确定插入顺序是否为重复序列。

• 如果尝试更新属于定期序列的插入顺序的 StartDate 或 EndDate，API 将返回错误。
• 如果更新属于定期序列的插入订单 的状态 ，状态更新将应用于该系列中的所有插入订单。

若要管理Microsoft广告 Web 应用程序中的定期插入订单，请参阅创建和编辑插入订单如何实现帮助文章。

语法

XML

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

JSON

{
  "AccountId": "LongValueHere",
  "AccountNumber": "ValueHere",
  "BookingCountryCode": "ValueHere",
  "BudgetRemaining": DoubleValueHere,
  "BudgetRemainingPercent": DoubleValueHere,
  "BudgetSpent": DoubleValueHere,
  "BudgetSpentPercent": DoubleValueHere,
  "Comment": "ValueHere",
  "EndDate": "ValueHere",
  "Id": "LongValueHere",
  "IsEndless": "ValueHere",
  "IsInSeries": "ValueHere",
  "IsUnlimited": "ValueHere",
  "LastModifiedByUserId": "LongValueHere",
  "LastModifiedTime": "ValueHere",
  "Name": "ValueHere",
  "NotificationThreshold": DoubleValueHere,
  "PendingChanges": {
    "ChangeStatus": "ValueHere",
    "Comment": "ValueHere",
    "EndDate": "ValueHere",
    "ModifiedDateTime": "ValueHere",
    "Name": "ValueHere",
    "NotificationThreshold": DoubleValueHere,
    "PurchaseOrder": "ValueHere",
    "ReferenceId": "LongValueHere",
    "RequestedByUserId": IntValueHere,
    "SpendCapAmount": DoubleValueHere,
    "StartDate": "ValueHere"
  },
  "PurchaseOrder": "ValueHere",
  "ReferenceId": "LongValueHere",
  "SeriesFrequencyType": "ValueHere",
  "SeriesName": "ValueHere",
  "SpendCapAmount": DoubleValueHere,
  "StartDate": "ValueHere",
  "Status": "ValueHere"
}

元素

InsertionOrder 对象具有以下元素：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。

元素	说明	数据类型
AccountId	应用插入顺序的帐户的标识符。 创建插入订单后，无法更新帐户标识符。 加： 必填 更新： 只读	long
AccountNumber	系统生成的帐号，用于标识Microsoft广告 Web 应用程序中的帐户。 帐户号的格式为 xxxxxxxx，其中 xxxxxxxx 是任意 8 个字母数字字符的系列。 加： 只读 更新： 只读	string
BookingCountryCode	仅供内部使用。 加： 对于某些帐户是必需的;对于某些帐户，可选。 更新： 只读	string
BudgetRemaining	插入顺序的运行余额。 运行余额值最初与 SpendCapAmount 相同，然后每次提供帐户中的广告时都会减少。 如果插入订单具有无限制的预算，则此元素为空。 加： 只读 更新： 只读	双
BudgetRemainingPercent	插入订单的剩余预算百分比。 此值的计算方式为 BudgetRemaining / SpendCapAmount。 如果插入订单具有无限制的预算，则此元素为空。 加： 只读 更新： 只读	双
BudgetSpent	插入订单的剩余余额。 剩余余额最初为 0 (零) ，然后每次提供帐户中的广告时，都会向 SpendCapAmount 增加。 如果插入订单具有无限制的预算，则此元素为空。 加： 只读 更新： 只读	双
BudgetSpentPercent	插入订单花费的预算百分比。 此值计算为 BudgetSpent / SpendCapAmount。 如果插入订单具有无限制的预算，则此元素为空。 加： 只读 更新： 只读	双
评论	插入顺序的说明。 说明限制为 100 个字符。 加： 自选 更新： 自选	string
EndDate	插入订单到期的日期。 结束日期必须晚于开始日期。 该日期存储在协调世界时 (UTC) 中。 仅使用指定字符串的月份、日和年。 如果指定日期的小时、分钟和秒，它们将被忽略。 有关日期和时间格式的信息，请参阅基元 XML 数据类型中的 dateTime 条目。 注意：如果插入订单没有结束日期， 则 EndDate 为空。 不支持添加或更新无限制的插入订单。 EndDate 在只读模式下运行。 加： 必填 更新： 自选。 如果尝试更新属于定期序列的插入顺序的 StartDate 或 EndDate，API 将返回错误。	dateTime
ID	标识插入顺序的系统生成的标识符。 加： 只读 更新： 只读和必需	long
IsEndless	确定插入订单是否没有结束日期。 如果值为 True，则插入顺序将没有结束日期，并且将忽略此插入顺序的 EndDate 。 加： 自选 更新： 自选	boolean
IsInSeries	确定插入顺序是否为定期序列。 如果值为 True，则插入顺序是定期序列的一部分。 如果尝试更新属于定期序列的插入顺序的 StartDate 或 EndDate，API 将返回错误。 如果更新属于定期序列的插入订单 的状态 ，状态更新将应用于该系列中的所有插入订单。 加： 只读 更新： 只读	boolean
IsUnlimited	确定插入订单是否具有无限制的预算。 如果值为 True，则插入订单将具有无限制的预算，并且将忽略此插入订单的 SpendCapAmount 。 加： 自选 更新： 自选	boolean
LastModifiedByUserId	要更新插入顺序的最后一个用户的标识符。 加： 只读 更新： 只读	long
LastModifiedTime	上次更新插入顺序的日期和时间。 该日期存储在协调世界时 (UTC) 中。 有关日期和时间格式的信息，请参阅基元 XML 数据类型中的 dateTime 条目。 加： 只读 更新： 只读	dateTime
名称	可用于引用此插入顺序的友好名称。 名称最多可以包含 100 个字符。 与客户的其他插入订单相比，名称不需要是唯一的。 加： 自选 更新： 自选	string
NotificationThreshold	已花费预算的百分比。 将百分比指定为 0 到 100 的值。 达到阈值时发送通知。 例如，如果将阈值设置为 70，计费服务会在你花费了预算的 70% 时发送通知。 如果不想接收通知，请将 设置为 NULL。 仅供内部使用。 加： 自选 更新： 自选	双
PendingChanges	可用于管理状态设置为“活动”、“已用”、“已过期”或“未启动”的已批准插入订单的更改。 加： 只读 更新： 自选	InsertionOrderPendingChanges
PurchaseOrder	可用于在每月发票中引用此插入订单的采购订单值。 此值将打印为每月发票中的采购订单。 采购订单最多可以包含 50 个字符。 加： 自选 更新： 自选	string
ReferenceId	仅供内部使用。 加： 自选 更新： 自选	long
SeriesFrequencyType	确定序列中订单的递归方式。 可能的值为 Monthly、BiMonthly、Quarterly 和 Yearly。 加： 只读 更新： 只读	string
SeriesName	定期插入订单系列的名称。 名称最多可以包含 100 个字符。 即使插入顺序后来从定期序列中删除，此元素将继续反映创建它的系列的名称。 加： 只读 更新： 只读	string
SpendCapAmount	此插入订单的预算。 预算是硬性限制。 当帐户达到此限制并且没有其他可用的插入顺序时，帐户的生命周期状态值将设置为 “暂停”。 如果插入订单具有无限制的预算，则此元素为空。 预算是要为插入订单花费的最大金额。 对于预算无限制的插入订单，预算受信用额度的限制。 在这种情况下，每个市场活动的每日预算决定了最大支出。 注意：不支持添加或更新无限制的插入订单。 SpendCapAmount 在只读模式下运行。 加： 必填 更新： 自选	双
StartDate	插入订单可以开始产生费用的日期。 开始日期必须晚于当前日期。 该日期存储在协调世界时 (UTC) 中。 仅使用指定字符串的月份、日和年。 如果指定日期的小时、分钟和秒，它们将被忽略。 有关日期和时间格式的信息，请参阅基元 XML 数据类型中的 dateTime 条目。 加： 必填 更新： 自选。 如果 Status 为 PendingUserReview，则只能通过此元素更新开始日期。 如果开始日期已过，则无法更改它。 如果尝试更新属于定期序列的插入顺序的 StartDate 或 EndDate，API 将返回错误。	dateTime
状态	插入顺序的状态。 加： 只读。 创建的插入订单会立即设置为“活动”、“NotStarted”或“已拒绝”。 更新： 需要批准或拒绝尚未批准的插入订单，或取消已批准的插入订单。 如果当前状态设置为 PendingUserReview，则只能通过此元素批准或拒绝。 仅当当前状态设置为“活动”、“已用尽”或“NotStarted”时，才能通过此元素取消。 插入订单状态为“活动”、“已用”、“已过期”或“未启动”后，即可进行新的更改，或者通过 PendingChanges 元素批准或拒绝当前挂起的更改。 调用 UpdateInsertionOrder 时，可以设置此 Status 元素或修改此对象的其他元素，但不能与其他属性更新并行更改状态。 如果更新属于定期序列的插入订单的状态，状态更新将应用于该系列中的所有插入订单。	InsertionOrderStatus

要求

服务： CustomerBillingService.svc v13
Namespace： https://bingads.microsoft.com/Customer/v13/Entities

使用者

AddInsertionOrder
SearchInsertionOrders
UpdateInsertionOrder