REST Resource: advertisers.lineItems

Resource: LineItem

A single line item.

JSON representation
{
  "name": string,
  "advertiserId": string,
  "campaignId": string,
  "insertionOrderId": string,
  "lineItemId": string,
  "displayName": string,
  "lineItemType": enum (LineItemType),
  "entityStatus": enum (EntityStatus),
  "updateTime": string,
  "partnerCosts": [
    {
      object (PartnerCost)
    }
  ],
  "flight": {
    object (LineItemFlight)
  },
  "budget": {
    object (LineItemBudget)
  },
  "pacing": {
    object (Pacing)
  },
  "frequencyCap": {
    object (FrequencyCap)
  },
  "partnerRevenueModel": {
    object (PartnerRevenueModel)
  },
  "conversionCounting": {
    object (ConversionCountingConfig)
  },
  "creativeIds": [
    string
  ],
  "bidStrategy": {
    object (BiddingStrategy)
  },
  "integrationDetails": {
    object (IntegrationDetails)
  },
  "inventorySourceIds": [
    string
  ]
}
Fields
name

string

Output only. The resource name of the line item.

advertiserId

string (int64 format)

Output only. The unique ID of the advertiser the line item belongs to.

campaignId

string (int64 format)

Output only. The unique ID of the campaign that the line item belongs to.

insertionOrderId

string (int64 format)

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

lineItemId

string (int64 format)

Output only. The unique ID of the line item. Assigned by the system.

displayName

string

Required. The display name of the line item.

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

lineItemType

enum (LineItemType)

Required. Immutable. The type of the line item.

entityStatus

enum (EntityStatus)

Required. Controls whether or not the line item can spend its budget and bid on inventory.

  • For lineItems.create method, only ENTITY_STATUS_DRAFT is allowed. To activate a line item, use lineItems.patch method and update the status to ENTITY_STATUS_ACTIVE after creation.
  • A line item cannot be changed back to ENTITY_STATUS_DRAFT status from any other status.
  • If the line item's parent insertion order is not active, the line item can't spend its budget even if its own status is ENTITY_STATUS_ACTIVE.
updateTime

string (Timestamp format)

Output only. The timestamp when the line item 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 line item.

If absent or empty in lineItems.create method, the newly created line item will inherit partner costs from its parent insertion order.

flight

object (LineItemFlight)

Required. The start and end time of the line item's flight.

budget

object (LineItemBudget)

Required. The budget allocation setting of the line item.

pacing

object (Pacing)

Required. The budget spending speed setting of the line item.

frequencyCap

object (FrequencyCap)

Required. The frequency capping setting of the line item.

partnerRevenueModel

object (PartnerRevenueModel)

Required. The partner revenue model setting of the line item.

conversionCounting

object (ConversionCountingConfig)

The conversion tracking setting of the line item.

creativeIds[]

string (int64 format)

The IDs of the creatives associated with the line item.

bidStrategy

object (BiddingStrategy)

Required. The bidding strategy of the line item.

integrationDetails

object (IntegrationDetails)

Integration details of the line item.

inventorySourceIds[]

string (int64 format)

The IDs of the private inventory sources assigned to the line item.

LineItemType

Possible types of a line item.

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

Enums
LINE_ITEM_TYPE_UNSPECIFIED Type value is not specified or is unknown in this version.
LINE_ITEM_TYPE_DISPLAY_DEFAULT Image, HTML5, native, or rich media ads.
LINE_ITEM_TYPE_DISPLAY_MOBILE_APP_INSTALL Display ads that drive installs of an app.
LINE_ITEM_TYPE_VIDEO_DEFAULT Video ads sold on a CPM basis for a variety of environments.
LINE_ITEM_TYPE_VIDEO_MOBILE_APP_INSTALL Video ads that drive installs of an app.
LINE_ITEM_TYPE_DISPLAY_MOBILE_APP_INVENTORY Display ads served on mobile app inventory.
LINE_ITEM_TYPE_VIDEO_MOBILE_APP_INVENTORY Video ads served on mobile app inventory.
LINE_ITEM_TYPE_AUDIO_DEFAULT Rtb Audio ads sold for a variety of environments.

LineItemFlight

Settings that control the active duration of a line item.

JSON representation
{
  "flightDateType": enum (LineItemFlightDateType),
  "dateRange": {
    object (DateRange)
  }
}
Fields
flightDateType

enum (LineItemFlightDateType)

Required. The type of the line item's flight dates.

dateRange

object (DateRange)

The flight start and end dates of the line item. They are resolved relative to the parent advertiser's time zone.

  • Required when flightDateType is LINE_ITEM_FLIGHT_DATE_TYPE_CUSTOM. Output only otherwise.
  • When creating a new flight, both startDate and endDate must be in the future.
  • An existing flight 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.

LineItemFlightDateType

Possible types of a line item's flight dates.

Enums
LINE_ITEM_FLIGHT_DATE_TYPE_UNSPECIFIED Type value is not specified or is unknown in this version.
LINE_ITEM_FLIGHT_DATE_TYPE_INHERITED The line item's flight dates are inherited from its parent insertion order.
LINE_ITEM_FLIGHT_DATE_TYPE_CUSTOM The line item uses its own custom flight dates.

LineItemBudget

Settings that control how budget is allocated.

JSON representation
{
  "budgetAllocationType": enum (LineItemBudgetAllocationType),
  "budgetUnit": enum (BudgetUnit),
  "maxAmount": string
}
Fields
budgetAllocationType

enum (LineItemBudgetAllocationType)

Required. The type of the budget allocation.

LINE_ITEM_BUDGET_ALLOCATION_TYPE_AUTOMATIC is only applicable when automatic budget allocation is enabled for the parent insertion order.

budgetUnit

enum (BudgetUnit)

Output only. The budget unit specifies whether the budget is currency based or impression based. This value is inherited from the parent insertion order.

maxAmount

string (int64 format)

The maximum budget amount the line item will spend. Must be greater than 0.

When budgetAllocationType is:

  • LINE_ITEM_BUDGET_ALLOCATION_TYPE_AUTOMATIC, this field is immutable and is set by the system.
  • LINE_ITEM_BUDGET_ALLOCATION_TYPE_FIXED, if budgetUnit is:
    • BUDGET_UNIT_CURRENCY, this field represents maximum budget amount to spend, in micros of the advertiser's currency. For example, 1500000 represents 1.5 standard units of the currency.
    • BUDGET_UNIT_IMPRESSIONS, this field represents the maximum number of impressions to serve.
  • LINE_ITEM_BUDGET_ALLOCATION_TYPE_UNLIMITED, this field is not applicable and will be ignored by the system.

LineItemBudgetAllocationType

Possible types of the budget allocation.

Enums
LINE_ITEM_BUDGET_ALLOCATION_TYPE_UNSPECIFIED Type value is not specified or is unknown in this version.
LINE_ITEM_BUDGET_ALLOCATION_TYPE_AUTOMATIC Automatic budget allocation is enabled for the line item.
LINE_ITEM_BUDGET_ALLOCATION_TYPE_FIXED A fixed max budget amount is allocated for the line item.
LINE_ITEM_BUDGET_ALLOCATION_TYPE_UNLIMITED No budget limit is applied to the line item.

PartnerRevenueModel

Settings that control how partner revenue is calculated.

JSON representation
{
  "markupType": enum (PartnerRevenueModelMarkupType),
  "markupAmount": string
}
Fields
markupType

enum (PartnerRevenueModelMarkupType)

Required. The markup type of the partner revenue model.

markupAmount

string (int64 format)

Required. The markup amount of the partner revenue model. Must be greater than or equal to 0.

  • When the markupType is set to be PARTNER_REVENUE_MODEL_MARKUP_TYPE_CPM, this field represents the CPM markup in micros of advertiser's currency. For example, 1500000 represents 1.5 standard units of the currency.
  • When the markupType is set to be PARTNER_REVENUE_MODEL_MARKUP_TYPE_MEDIA_COST_MARKUP, this field represents the media cost percent markup in millis. For example, 100 represents 0.1% (decimal 0.001).
  • When the markupType is set to be PARTNER_REVENUE_MODEL_MARKUP_TYPE_TOTAL_MEDIA_COST_MARKUP, this field represents the total media cost percent markup in millis. For example, 100 represents 0.1% (decimal 0.001).

PartnerRevenueModelMarkupType

Possible markup types of the partner revenue model.

Enums
PARTNER_REVENUE_MODEL_MARKUP_TYPE_UNSPECIFIED Type value is not specified or is unknown in this version.
PARTNER_REVENUE_MODEL_MARKUP_TYPE_CPM Calculate the partner revenue based on a fixed CPM.
PARTNER_REVENUE_MODEL_MARKUP_TYPE_MEDIA_COST_MARKUP Calculate the partner revenue based on a percentage surcharge of its media cost.
PARTNER_REVENUE_MODEL_MARKUP_TYPE_TOTAL_MEDIA_COST_MARKUP Calculate the partner revenue based on a percentage surcharge of its total media cost, which includes all partner costs and data costs.

ConversionCountingConfig

Settings that control how conversions are counted.

All post-click conversions will be counted. A percentage value can be set for post-view conversions counting.

JSON representation
{
  "postViewCountPercentageMillis": string,
  "floodlightActivityConfigs": [
    {
      object (TrackingFloodlightActivityConfig)
    }
  ]
}
Fields
postViewCountPercentageMillis

string (int64 format)

The percentage of post-view conversions to count, in millis (1/1000 of a percent). Must be between 0 and 100000 inclusive.

For example, to track 50% of the post-click conversions, set a value of 50000.

floodlightActivityConfigs[]

object (TrackingFloodlightActivityConfig)

The Floodlight activity configs used to track conversions.

The number of conversions counted is the sum of all of the conversions counted by all of the Floodlight activity IDs specified in this field.

TrackingFloodlightActivityConfig

Settings that control the behavior of a single Floodlight activity config.

JSON representation
{
  "floodlightActivityId": string,
  "postClickLookbackWindowDays": integer,
  "postViewLookbackWindowDays": integer
}
Fields
floodlightActivityId

string (int64 format)

Required. The ID of the Floodlight activity.

postClickLookbackWindowDays

integer

Required. The number of days after an ad has been clicked in which a conversion may be counted. Must be between 0 and 90 inclusive.

postViewLookbackWindowDays

integer

Required. The number of days after an ad has been viewed in which a conversion may be counted. Must be between 0 and 90 inclusive.

Methods

bulkEditLineItemAssignedTargetingOptions

Bulk edits targeting options under a single line item.

bulkListLineItemAssignedTargetingOptions

Lists assigned targeting options of a line item across targeting types.

create

Creates a new line item.

delete

Deletes a line item.

get

Gets a line item.

list

Lists line items in an advertiser.

patch

Updates an existing line item.