REST Resource: advertisers.insertionOrders

  • Display & Video 360 API v2 has sunset.

  • The InsertionOrder resource represents a single insertion order with various settings like display name, type, status, pacing, frequency cap, performance goal, budget, and bid strategy.

  • Insertion orders can have different types, including Real-time bidding (RTB) and Over-the-top (OTT).

  • Insertion order budgets can be currency or impression based and allocated across different date ranges using budget segments, with options for budget automation.

  • The only valid billable outcome for an insertion order is BILLABLE_OUTCOME_PAY_PER_IMPRESSION.

Resource: InsertionOrder

A single insertion order.

JSON representation 
{
  "name": string,
  "advertiserId": string,
  "campaignId": string,
  "insertionOrderId": string,
  "displayName": string,
  "insertionOrderType": enum (InsertionOrderType),
  "entityStatus": enum (EntityStatus),
  "updateTime": string,
  "partnerCosts": [
    {
      object (PartnerCost)
    }
  ],
  "pacing": {
    object (Pacing)
  },
  "frequencyCap": {
    object (FrequencyCap)
  },
  "integrationDetails": {
    object (IntegrationDetails)
  },
  "performanceGoal": {
    object (PerformanceGoal)
  },
  "budget": {
    object (InsertionOrderBudget)
  },
  "bidStrategy": {
    object (BiddingStrategy)
  },
  "reservationType": enum (ReservationType),
  "billableOutcome": enum (BillableOutcome)
}
Fields
name

string

Output only. The resource name of the insertion order.
advertiserId

string (int64 format)

Output only. The unique ID of the advertiser the insertion order belongs to.
campaignId

string (int64 format)

Required. Immutable. The unique ID of the campaign that the insertion order belongs to.
insertionOrderId

string (int64 format)

Output only. The unique ID of the insertion order. Assigned by the system.
displayName

string

Required. The display name of the insertion order.

Must be UTF-8 encoded with a maximum size of 240 bytes.
insertionOrderType

enum (InsertionOrderType)

The type of insertion order.

If this field is unspecified in creation, the value defaults to RTB.
entityStatus

enum (EntityStatus)

Required. Controls whether or not the insertion order can spend its budget and bid on inventory.

  • For insertionOrders.create method, only ENTITY_STATUS_DRAFT is allowed. To activate an insertion order, use insertionOrders.patch method and update the status to ENTITY_STATUS_ACTIVE after creation.
  • An insertion order cannot be changed back to ENTITY_STATUS_DRAFT status from any other status.
  • An insertion order cannot be set to ENTITY_STATUS_ACTIVE if its parent campaign is not active.
updateTime

string (Timestamp format)

Output only. The timestamp when the insertion order was last updated. Assigned by the system.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".
partnerCosts[]

object (PartnerCost)

The partner costs associated with the insertion order.

If absent or empty in insertionOrders.create method, the newly created insertion order will inherit partner costs from the partner settings.
pacing

object (Pacing)

Required. The budget spending speed setting of the insertion order.
frequencyCap

object (FrequencyCap)

Required. The frequency capping setting of the insertion order.
integrationDetails

object (IntegrationDetails)

Additional integration details of the insertion order.
performanceGoal

object (PerformanceGoal)

Required. Performance goal of the insertion order.
budget

object (InsertionOrderBudget)

Required. The budget allocation settings of the insertion order.
bidStrategy

object (BiddingStrategy)

The bidding strategy of the insertion order. By default, fixedBid is set.
reservationType

enum (ReservationType)

Output only. The reservation type of the insertion order.
billableOutcome

enum (BillableOutcome)

Immutable. The billable outcome of the insertion order.

Outcome based buying is deprecated. BILLABLE_OUTCOME_PAY_PER_IMPRESSION is the only valid value.

InsertionOrderType

Possible types of an Insertion Order.

The type of the Insertion Order determines which settings and options are applicable, such as the format of the ads or targeting options.

Enums
INSERTION_ORDER_TYPE_UNSPECIFIED Insertion order type is not specified or is unknown.
RTB Real-time bidding.
OVER_THE_TOP Over-the-top.

InsertionOrderBudget

Settings that control how insertion order budget is allocated.

JSON representation 
{
  "budgetUnit": enum (BudgetUnit),
  "automationType": enum (InsertionOrderAutomationType),
  "budgetSegments": [
    {
      object (InsertionOrderBudgetSegment)
    }
  ]
}
Fields
budgetUnit

enum (BudgetUnit)

Required. Immutable. The budget unit specifies whether the budget is currency based or impression based.
automationType

enum (InsertionOrderAutomationType)

The type of automation used to manage bid and budget for the insertion order.

If this field is unspecified in creation, the value defaults to INSERTION_ORDER_AUTOMATION_TYPE_NONE.
budgetSegments[]

object (InsertionOrderBudgetSegment)

Required. The list of budget segments. Use a budget segment to specify a specific budget for a given period of time an insertion order is running.

InsertionOrderAutomationType

Possible options for automating insertion order bid and budget.

Enums
INSERTION_ORDER_AUTOMATION_TYPE_UNSPECIFIED Insertion order automation option is not specified or is unknown in this version.
INSERTION_ORDER_AUTOMATION_TYPE_BUDGET Automatic budget allocation. Allow the system to automatically shift budget to owning line items to optimize performance defined by performanceGoal. No automation on bid settings.
INSERTION_ORDER_AUTOMATION_TYPE_NONE No automation of bid or budget on insertion order level. Bid and budget must be manually configured at the line item level.
INSERTION_ORDER_AUTOMATION_TYPE_BID_BUDGET Allow the system to automatically adjust bids and shift budget to owning line items to optimize performance defined by performanceGoal.

InsertionOrderBudgetSegment

Settings that control the budget of a single budget segment.

JSON representation 
{
  "budgetAmountMicros": string,
  "description": string,
  "dateRange": {
    object (DateRange)
  },
  "campaignBudgetId": string
}
Fields
budgetAmountMicros

string (int64 format)

Required. The budget amount the insertion order will spend for the given dateRange. The amount is in micros. Must be greater than 0. For example, 500000000 represents 500 standard units of the currency.
description

string

The budget segment description. It can be used to enter Purchase Order information for each budget segment and have that information printed on the invoices.

Must be UTF-8 encoded.
dateRange

object (DateRange)

Required. The start and end date settings of the budget segment. They are resolved relative to the parent advertiser's time zone.

  • When creating a new budget segment, both startDate and endDate must be in the future.
  • An existing budget segment with a startDate in the past has a mutable endDate but an immutable startDate.
  • endDate must be the startDate or later, both before the year 2037.
campaignBudgetId

string (int64 format)

The budgetId of the campaign budget that this insertion order budget segment is a part of.

BillableOutcome

Possible billable outcomes for an insertion order.

Enums
BILLABLE_OUTCOME_UNSPECIFIED Unspecified billable outcome.
BILLABLE_OUTCOME_PAY_PER_IMPRESSION Pay per impressions.
BILLABLE_OUTCOME_PAY_PER_CLICK

Pay per click.
BILLABLE_OUTCOME_PAY_PER_VIEWABLE_IMPRESSION

Pay per active view.

Methods

create

 Creates a new insertion order.

delete

 Deletes an insertion order.

get

 Gets an insertion order.

list

 Lists insertion orders in an advertiser.

listAssignedTargetingOptions

 Lists assigned targeting options of an insertion order across targeting types.

patch

 Updates an existing insertion order.