REST Resource: advertisers.insertionOrders

{
  "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)
  },
  "kpi": {
    object (Kpi)
  },
  "budget": {
    object (InsertionOrderBudget)
  },
  "bidStrategy": {
    object (BiddingStrategy)
  },
  "reservationType": enum (ReservationType),
  "optimizationObjective": enum (OptimizationObjective)
}

string

Output only. The resource name of the insertion order.

string (int64 format)

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

string (int64 format)

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

string (int64 format)

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

string

Required. The display name of the insertion order.

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

enum (InsertionOrderType)

The type of insertion order.

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

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.

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

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.

object (Pacing)

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

pacingType PACING_TYPE_ASAP is not compatible with pacingPeriod PACING_PERIOD_FLIGHT.

object (FrequencyCap)

Required. The frequency capping setting of the insertion order.

object (IntegrationDetails)

Additional integration details of the insertion order.

object (Kpi)

Required. The key performance indicator (KPI) of the insertion order.

This is represented as referred to as the "Goal" in the Display & Video 360 interface.

object (InsertionOrderBudget)

Required. The budget allocation settings of the insertion order.

object (BiddingStrategy)

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

enum (ReservationType)

Output only. The reservation type of the insertion order.

enum (OptimizationObjective)

Optional. The optimization objective of the insertion order.

This field is only available to allowlisted customers. If a customer is not allowlisted, this field will be null and attempts to set it will return an error.

{
  "kpiType": enum (KpiType),
  "kpiAlgorithmId": string,

  // Union field kpi_value can be only one of the following:
  "kpiAmountMicros": string,
  "kpiPercentageMicros": string,
  "kpiString": string
  // End of list of possible types for union field kpi_value.
}

enum (KpiType)

Required. The type of KPI.

string (int64 format)

Optional. Custom Bidding Algorithm ID associated with KPI_CUSTOM_IMPRESSION_VALUE_OVER_COST. This field is ignored if the proper KPI is not selected.

string (int64 format)

The goal amount, in micros of the advertiser's currency.

Applicable when kpiType is one of:

• KPI_TYPE_CPM
• KPI_TYPE_CPC
• KPI_TYPE_CPA
• KPI_TYPE_CPIAVC
• KPI_TYPE_VCPM

For example: 1500000 represents 1.5 standard units of the currency.

string (int64 format)

The decimal representation of the goal percentage in micros.

Applicable when kpiType is one of:

• KPI_TYPE_CTR
• KPI_TYPE_VIEWABILITY
• KPI_TYPE_CLICK_CVR
• KPI_TYPE_IMPRESSION_CVR
• KPI_TYPE_VTR
• KPI_TYPE_AUDIO_COMPLETION_RATE
• KPI_TYPE_VIDEO_COMPLETION_RATE

For example: 70000 represents 7% (decimal 0.07).

string

A KPI string, which can be empty. Must be UTF-8 encoded with a length of no more than 100 characters.

Applicable when kpiType is KPI_TYPE_OTHER.

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

enum (BudgetUnit)

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

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.

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.

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

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.

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.

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.

string (int64 format)

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