REST Resource: advertisers.insertionOrders

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

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

    Uses RFC 3339, where generated output will always be Z-normalized and uses 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z" , "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30" .

    partnerCosts[]

    object ( PartnerCost )

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

    pacingType PACING_TYPE_ASAP is not compatible with pacingPeriod PACING_PERIOD_FLIGHT .

    frequencyCap

    object ( FrequencyCap )

    Required. The frequency capping setting of the insertion order.

    integrationDetails

    object ( IntegrationDetails )

    Optional. Additional integration details of the insertion order.

    kpi

    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.

    budget

    object ( InsertionOrderBudget )

    Required. The budget allocation settings of the insertion order.

    bidStrategy

    object ( BiddingStrategy )

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

    reservationType

    enum ( ReservationType )

    Output only. The reservation type of the insertion order.

    optimizationObjective

    enum ( OptimizationObjective )

    Optional. The optimization objective of the insertion order.

    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.

    Kpi

    Settings that control the key performance indicator, or KPI, of an insertion order.

    JSON representation 
     { 
 "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 
. 
 }
    Fields
    kpiType

    enum ( KpiType )

    Required. The type of KPI.

    kpiAlgorithmId

    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.

    Union field kpi_value . Required. The value of the KPI. The relevant field corresponds to the kpi_type . kpi_value can be only one of the following:
    kpiAmountMicros

    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.

    kpiPercentageMicros

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

    kpiString

    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 .

    KpiType

    Possible key performance indicator (KPI) types.

    Enums
    KPI_TYPE_UNSPECIFIED KPI type is not specified or is unknown in this version.
    KPI_TYPE_CPM The KPI is CPM (cost per mille).
    KPI_TYPE_CPC The KPI is CPC (cost per click).
    KPI_TYPE_CPA The KPI is CPA (cost per action).
    KPI_TYPE_CTR The KPI is CTR (click-through rate) percentage.
    KPI_TYPE_VIEWABILITY The KPI is Viewability percentage.
    KPI_TYPE_CPIAVC The KPI is CPIAVC (cost per impression audible and visible at completion).
    KPI_TYPE_CPE The KPI is CPE (cost per engagement).
    KPI_TYPE_CPV The KPI is set in CPV (cost per view).
    KPI_TYPE_CLICK_CVR The KPI is click conversion rate (conversions per click) percentage.
    KPI_TYPE_IMPRESSION_CVR The KPI is impression conversion rate (conversions per impression) percentage.
    KPI_TYPE_VCPM The KPI is VCPM (cost per thousand viewable impressions).
    KPI_TYPE_VTR The KPI is YouTube view rate (YouTube views per impression) percentage.
    KPI_TYPE_AUDIO_COMPLETION_RATE The KPI is audio completion rate (complete audio listens per impression) percentage.
    KPI_TYPE_VIDEO_COMPLETION_RATE The KPI is video completion rate (complete video views per impression) percentage.
    KPI_TYPE_CPCL The KPI is set in CPCL (cost per complete audio listen).
    KPI_TYPE_CPCV The KPI is set in CPCV (cost per complete video view).
    KPI_TYPE_TOS10 The KPI is set in rate of time on screen 10+ seconds (Percentage of measurable, non-skippable impressions that were on the screen for at least 10 seconds).
    KPI_TYPE_MAXIMIZE_PACING The KPI is set to maximize brand impact while prioritizing spending the full budget.
    KPI_TYPE_CUSTOM_IMPRESSION_VALUE_OVER_COST The KPI is set in custom impression value divided by cost.
    KPI_TYPE_OTHER The KPI is some other value.

    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 )

    Optional. 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 kpi . 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 kpi .

    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

    Optional. 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)

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

    OptimizationObjective

    Possible types of the optimization objectives.

    Enums
    OPTIMIZATION_OBJECTIVE_UNSPECIFIED Type value is not specified or is unknown in this version.
    CONVERSION Prioritize impressions that increase sales and conversions.
    CLICK Prioritize impressions that increase website traffic, apps, app stores.
    BRAND_AWARENESS Prioritize impressions of specific quality.
    CUSTOM Objective is defined by the assigned custom bidding algorithm.
    NO_OBJECTIVE Objective is not defined. Any KPI or bidding strategy can be used.

    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.
    Design a Mobile Site
    View Site in Mobile | Classic
    Share by: