Activate Line Item

All line items created using the Display & Video 360 API are initially created in a draft state. In this draft state, line items don't serve ads, so you are free to adjust settings and targeting without those changes affecting any current ad serving. This page describes the steps you should take to confirm that your line item is ready for serving ads, and how to update its status to active.

What to do before activation

Given that line items are the manner in which your ad revenue is spent through ad buying and serving, it is important to make sure that the line item will serve ads as intended when activated. Below are a few things to consider before activating your line item:

• Make sure the flight settings are correct: Check the line item's flight field to make sure that the flight window for the line item is set correctly. The flight window of a line item may be custom to the line item or inherited by the parent insertion order. If controlled directly by a manual trigger, the line item automatically inherits the flight of the insertion order.
• Verify that there are no warnings blocking the serving of the line item: Use advertisers.lineItems.get to retrieve a line item resource and check the field warningMessages to verify that the line item has no warnings that may hinder the serving of the line item. The LineItemWarningMessage enum notes the impact of each warning.
• Confirm that all parent resources are also active: An active line item will not begin to serve ads if its parent advertiser, campaign, or insertion order are not active. Retrieve these resources using the GET methods in the Advertisers, Campaigns, and Insertion Orders services.

Activate a line item

Line items can be updated by using the PATCH method in the Line Items service.

The following code is an example of how to update a line item’s entity status to active:

Java

// Create the line item structure.
LineItem lineItem = new LineItem();
lineItem.setEntityStatus("ENTITY_STATUS_ACTIVE");

// Configure the patch request.
LineItems.Patch request = service.advertisers().lineItems()
   .patch(advertiser-id, line-item-id, lineItem);

// Set update mask to only update entity status.
request.setUpdateMask("entityStatus");

// Update the line item.
LineItem response = request.execute();

// Display the new line item entity status.
System.out.printf("LineItem %s now has entity status %s.",
   response.getName(),
   response.getEntityStatus());

Python

# Create a line item object with only updated entity status.
line_item_obj = {
    'entityStatus': 'ENTITY_STATUS_Active',
}

# Update the line item.
lineItem = service.advertisers().lineItems().patch(
    advertiserId=advertiser-id,
    lineItemId=line-item-id,
    updateMask="entityStatus",
    body=line_item_obj
).execute()

# Display the line item's new entity status
print("Line Item %s now has entity status %s." % (lineItem["name"], lineItem["entityStatus"]))

PHP

// Create line item with updated fields.
$lineItem = new Google_Service_DisplayVideo_LineItem();
$lineItem->setEntityStatus('ENTITY_STATUS_ACTIVE');

// Create request parameter array with update mask.
$optParams = array('updateMask' => 'entityStatus');

// Call the API, updating the entity status for the identified line item.
$result = $this->service->advertisers_lineItems->patch(
    advertiser-id,
    line-item-id,
    $lineItem,
    $optParams
);

printf(
    'Line Item %s now has entity status %s.\n',
    $result['name'],
    $result['entityStatus']
);

Serve using a manual trigger

Even when active, a line item only serves ads during periods dictated by its flight. Within the date range of a line item's flight, ad serving can be more precisely controlled through the use of a manual trigger.

A manual trigger is a switch that allows the line item to quickly begin serving ads for a short period of time upon activation. Once activated, the line item will serve ads for a set period of time or until the manual trigger is deactivated.

Only one manual trigger can be associated with a line item at a time. You can retrieve the ID for the desired manual trigger through the Manual Trigger LIST method and assign that ID to a line item by updating the line item's flight field.

Note: When associated with a manual trigger, a line item inherits the flight date range of its parent insertion order. Outside of that flight date range, A line item will not serve ads when the manual trigger is activated.

The following code is an example of how to update a line item’s flight to add a manual trigger:

Java

// Create the line item structure.
LineItem lineItem = new LineItem();

// Create and set the line item flight.
LineItemFlight lineItemFlight = new LineItemFlight();
lineItemFlight
   .setFlightDateType("LINE_ITEM_FLIGHT_DATE_TYPE_TRIGGER");
lineItemFlight
   .setTriggerId(manual-trigger-id);
lineItem.setFlight(lineItemFlight);

// Configure the patch request.
LineItems.Patch request = service.advertisers().lineItems()
   .patch(advertiser-id, line-item-id, lineItem);

// Set update mask to only update flight.
request.setUpdateMask("flight");

// Update the line item.
LineItem response = request.execute();

// Display the new manual trigger ID associated with the line item.
System.out.printf("Line Item %s is now associated with manual trigger ID %s.",
   response.getName(),
   response.getFlight().getTriggerId());

Python

# Create a line item object with only the updated flight.
line_item_obj = {
  'flight': {
    'flightDateType': 'LINE_ITEM_FLIGHT_DATE_TYPE_TRIGGER',
    'triggerId': manual-trigger-id
  },
}

# Update the line item.
lineItem = service.advertisers().lineItems().patch(
  advertiserId=advertiser-id,
  lineItemId=line-item-id,
  updateMask="flight",
  body=line_item_obj
).execute()

# Display the line item's new entity status
print("Line Item %s is now associated with manual trigger ID %s."
      % (lineItem["name"], lineItem["flight"]["triggerId"]))

PHP

// Create line item.
$lineItem = new Google_Service_DisplayVideo_LineItem();

// Create new flight object identifying the manual trigger ID.
$flight = new Google_Service_DisplayVideo_LineItemFlight();
$flight->setFlightDateType('LINE_ITEM_FLIGHT_DATE_TYPE_TRIGGER');
$flight->setTriggerId(manual-trigger-id);

// Set flight on updated line item.
$lineItem->setFlight($flight);

// Create request parameter array with update mask.
$optParams = array('updateMask' => 'flight');

// Call the API, updating the entity status for the identified line item.
$result = $this->service->advertisers_lineItems->patch(
    advertiser-id,
    line-item-id,
    $lineItem,
    $optParams
);

printf(
    'Line Item %s is now associated with manual trigger ID %s.\n',
    $result['name'],
    $result['flight']['triggerId']
);

Once the manual trigger is associated with the line item, you can have your line item start to serve ads by activating the manual trigger. The line item will serve ads for the amount of time dictated by the trigger's activationDurationMinutes field, or until the trigger is deactivated.