Line Item V2 API

Line Items API Guide

API documentation:

• https://docs.beeswax.com/v2.0/reference/listlineitems
• https://docs.beeswax.com/v2.0/reference/createlineitem
• https://docs.beeswax.com/v2.0/reference/updatelineitem

API Guide:

Users checklist:

• Check whether your users access tokens or need new authentication

Migration from v1 to v2 outline:

• For the most part, the changes in Line Items V2 are in the API response. Previously, it was a one-level structure or “flat”, where all fields are at the root level. This document outlines each change and compares v1 against v2
• The outline below describes the V1 endpoint in the left column, and the equivalent V2 endpoint in the right column. This endpoint takes different parameters and data so it is important to check what is being supported in this V2 endpoint.
• Important note: all values in the v2 API response are CASE SENSITIVE

CRUD Calls:

• Due to the workflow changes, our API endpoints will require different fields per endpoint. When make a specific call, the required fields vary.

Endpoints:

• POST rest/v2/line-items
• GET rest/v2/line-items/{id}
• PUT rest/v2/line-items/{id}
• PATCH rest/v2/line-items/{id}
• DELETE rest/v2/line-items/{id}

Key API Changes and Comparisons: Descriptive Strings

Change #1: Type

• We use things like descriptive strings for some of the fields that will be listed in the API schema, rather than primary key references to static data
• For the following endpoint GET rest/v2/line-items/{id}
• “Line_item_type_id” will change to “type” and support the enum of either banner, video, or native values

Type

Change #2: Budget Type

• For the following endpoint rest/v2/line-items/{id}
• “budget_type” will now support the enum of either spend, impressions, or spend with vendor fees values

Budget Type

Nested Structures

In the V2 API response, we implemented a nested object structure for better readability.

Change #3: Bidding

• For the following endpoint rest/v2/line-items the following changes have been made from V1 to V2.
• These changes are applicable to GET, POST, PATCH and PUT
• In the representation of the bidding field, the names were changed
  • The bid_shading and bid_shading_win_rate_control fields were merged into one: bid_shading_control.
  • This field will take the same values as bid_shading_win_rate_control
• When specifying it in the payload, we automatically determine that the bid_shading field is enabled (this logic happens on the backend side).

Bidding

Change #4: SKad Network

• For the following endpoint rest/v2/line-items
• In API V2, for skad network, we have logic to define the enable_skad_tracking field as enabled
• If there is at least one field from assignment_level and target_skad is not null.

SKAd Network

Change #5: Revenue

• For the following endpoint rest/v2/line-items
• In API V2, for revenue, we changed the field structure
• Revenue_type and revenue_amount were merged into revenue with sub elements of type & amount.
  • “type” values can be:
    • “CPM” -- Per Mille
    • “CPA” -- Per Acquisition
    • “CPC” -- Per Click
    • “CPCV” -- Per Completed Video
    • “CPI” -- Per Install
  • “amount” field accepts a string value

Revenue

Change #6: Budget, spend & impressions

• For the following endpoint rest/v2/line-items
• In API V1, the line-item budget view includes a budget_type field that defines the value and type of the budget and daily_budget fields, as well as budget fields in periods
• In API V2, by design, we separated budgets into independent fields for impressions and spend amounts.
  • All fields in the spend_budget and impressions_budget objects are mandatory.
  • Depending on the line-item budget type, one of the impressions_budget or spend_budget parameters can be null.

Budget

Impressions

Spend

Change #7: Ghost Bidding

• For the following endpoint GET rest/v2/line-items/{id}
• In API V1:
  • ghost_bidding_id_type
  • ghost_bidding_id_vendor_id
• In API V2, by design, we separated ghost_bidding to be
  • id_type
  • id_vendor
  • id_vendor_id
• All fields in the spend_budget and impressions_budget objects are mandatory and both fields can be empty.

Change #8: Segment Extension & Vendors

• For the following endpoint GET rest/v2/line-items/{id}
• Now the API represents the existing vendors as a list of objects. Previously it was a list of strings.
• In API V1:
  • segment_extension_default
  • segment_extension_type_default
  • segment_extension_vendors_default
• In API V2:
• segment_extension:
  • extension_type
  • segment_type
• Vendors
  • name

Change #9: Frequency caps

• For the following endpoint GET rest/v2/line-items/{id}
• The API now separates this into two fields, one of which is the same set of options used in ghost bidding and experiments, and the other is the use_fallback field.
• Also, the id_vendor field is present here as the name of the vendor.

Frequency caps accepts seven different options:

• Standard
• Standard with Fallback
• IP Address
• Person
• Person with Fallback
• Household
• Household with Fallback

V2 API structure:

• Id_type
• Use_fallback
• Id_vendor
• Id_vendor_id
• Limits:
  • Duration
  • impressions

Change #10: Vendor feeds, Custom event associations, and flights

• In V1, such entities were created using separate endpoints
• In V2, they are included in this endpoint: GET rest/v2/line-items/{id}
• The structure and are expected in payload. These entities are...

Vendor feeds

Change #11: Realtime Line Item Stats

• In V1, the realtime stats graph used this endpoint: /rest/line_item_performance_statistic
• In V2, the endpoint will change to: rest/v2/line-items/{id}/performance-statistics
• Other key notes for V2:
  • The API only returns statistics for one line item at a time.
  • The response is generated from the line_item_performance_statistics table.
• Additionally, the endpoint also accepts a new query parameter: window hours.
  • Example: /rest/v2/line-items/{id}/performance-statistics?windows_hours=12

Change #12: Guaranteed Line Items

• For the following endpoint /rest/v2/targeting-expressions
• The endpoint now allows for both a deal_id and a deal_list

Change #13: Creative Association endpoint

• A new endpoint has been created for creative associations
• In V2, the endpoint is: rest/v2/line-items/{line_item_id}/creatives
• This endpoint will now support the following:
  • List
  • Bulk selection
  • Add as association

To update all creative associations for a line item:

To update a singlular creative association:

To add a creative line item association:

To delete multiple creatives line item association:

Custom Event Associations

Now this is a list of ids that are associated (when getting) or that need to be associated (when creating or updating).

Flights

As for flights, in addition to being included in the line item endpoint, they are now divided into active_flights and past_flight in accordance with the new requirements. Only active flights are editable.

Read-Only fields

There are some fields made read-only in V2: spend, impressions, account, advertiser, create_date, update_date, past_flights. Removed fields The following fields have been removed from API V2 representation:

• last_active, line_item_version,
• pacing (at the root level, not from the bidding field)
• buzz_key, push_status
• push_update.

Errors & Warnings

Overview

In API V1, the general process for creating a line item involves sending a POST request to the /line_item/strict endpoint, which returns an HTTP 4XX message for any warnings it encounters. The user can bypass these warnings by clicking Save Anyway.

In the V2 API, we introduced the line-items/{id}/validate endpoint, which response with errors, warnings, and informational messages. The V2 user flow requires warnings to be issued when the line item is updated, so the endpoint only supports PUT/PATCH (not POST/GET). The fields required to initially create the line item should not raise any warnings. This endpoint expects the same body as the line item endpoint, and the API response compared to V1 looks like this:

New Feature: Duplication

In Line Items V2 duplication is now available via the API.

• First, the user needs to find out the list of available options (sections) for duplication.
• This can be achieved by sending a GET request to the line-items/245/duplicate endpoint.
  • GET rest/v2/line-items/245/duplicate
  • Retrieve the above JSON representation to initiate a duplication. The duplicate object is a list of strings that describes a list of entities that will be duplicated. Those whose Criteria [for duplication] is met below will be included in the JSON response.
• Next, the users need to pass the entities they want to copy as payload in the POST request.
  • POST rest/v2/line-items/245/duplicate
  • Creates a new line item and performs the Duplication action described below for each of the keys in the duplicate key of the submitted JSON payload. The response value should be the same representation as the line item detail endpoint.

New Feature: Bulk Edit

In Line Items V2 bulk edit is now available via the API. We implemented a new nested endpoint called: /rest/v2/line-items/bulk. See below for the supported endpoints and response body's:

• Bulk edit support the following request body:
  • List of objects

• Bulk edit support the following request body:
  • Objects with request parameters

Note:

• The API response on a successful update will consist of an array of edited serialized line items.
• The validations (such as errors and warnings) should work in the same way as for the initial endpoint. Diving into the technical implementation - if a field was not provided in the request body, it should be taken from an existing instance on the backend side.