Guides
Beeswax HomeGuidesAPI Reference

In Depth Overview of Line Item V2 Changes

All changes related to line item v2

Line Item Type

  • “Line_item_type_id” will change to “type” and support the enum of either banner, video, or native values
Old ValueNew Value
0Banner
1Video
2Native
{
	"line_item_type_id": 0,
}

{ 
    "type": "banner", 
}

Budget Type

  • “budget_type” will now support the enum of either spend, impressions, or spend with vendor fees values
Old ValueNew Value
0spend
1impressions
2spend including vendor fees
{
	"budget_type": 2,
}

{ 
    "budget_type": "spend", 
}

Bidding

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": { 
        "bidding_strategy": "CPM", 
        "custom": false, 
        "pacing": "none", 
        "values": { 
            "cpm_bid": 10 
        }, 
        "bid_shading": 0, 
        "bid_shading_win_rate_control": "NORMAL" 
    }, 
    … 
}

{
    … 
    "bidding": { 
        "strategy": "CPM", 
        "values": { 
            "cpm_bid": 10 
        }, 
        "pacing": "none", 
        "custom": false, 
        "bid_shading_control": "normal" 
    },
    … 
}

Budget, Spend and Impressions

  • 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_type": "0", 
    "line_item_budget": 1000, 
    "daily_budget": null, 
}

{ 
    … 
    "budget_type": "spend", 
    "spend_budget": { 
        "lifetime": "1000.00", 
        "daily": null 
    }, 
    "impressions_budget": null, 
    … 
}

Flights

  • Active flights and past flights are now divided into separate elements

{ 

… 
{
"active_flights": [ 
    { 
        "id": 2, 
        "name": "Flight 2", 
        "start_date": "2022-10-17 00:00:00", 
        "end_date": "2022-10-18 23:59:59", 
        "spend_budget": "20.00", 
        "impressions_budget": null 
    } 
], 
"past_flights": [ 
    { 
        "id": 1, 
        "name": "Flight 1", 
        "start_date": "2022-10-14 00:00:00", 
        "end_date": "2022-10-15 23:59:59", 
        "spend_budget": "5.00", 
        "impressions_budget": null 
    } 
 ], 
}
…

Frequency Caps

  • Frequency caps accepts seven different options:
    • Standard
    • Standard with Fallback
    • IP Address
    • Person
    • Person with Fallback
    • Household
    • Household with Fallback

V2 API structure: 

{
"frequency_caps": { 
    "id_type": "STANDARD", 
    "use_fallback": false, 
    "id_vendor": null, 
    "id_vendor_id": null, 
    "limits": [ 
        { 
            "duration": 86400, 
            "impressions": 1 
        } 
    ] 
	}, 
}

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

Guaranteed Line Items

  • For the following endpoint /rest/v2/targeting-expressions
  • The endpoint now allows for both a deal_id and a deal_list
  • In addition, for cases where the user created a guaranteed line item with a deal_id_list in V2 and then switched back to V1 (hypothetically unlikely), we will create a script that will clear this key, but it will be done after the beta release.

Creative Association endpoint

A new endpoint has been created for creative associations This endpoint will now support the following:

  • List
  • Bulk selection
  • Add as association

Details are:

  • GET rest/v2/line-items/{line_item_id}/creatives
  • POST rest/v2/line-items/{line_item_id}/creatives
  • PUT rest/v2/line-items/{line_item_id}/creatives
  • PATCH rest/v2/line-items/{line_item_id}/creatives/{cli_id}
{
  "active": true, 
  "weight": null, 
  "start_date": "2020-04-02 09:20:23", 
  "end_date": "2020-04-02 09:20:23", 
  "creative_id": 231, 
  "creative_name": "Creative Name", 
  "creative_type": "banner" 
  "thumbnail_url": "/canary2/1/1/thumb/25_12_banner300x250_thumb.jpg", 
  "template_id": 4, 
  "height": 250, 
  "width": 300, 
  "id": 1 
}

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

{ 
    … 
    "event_ids": [1, 2, 3], 
    … 
}

Revenue

  • 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
{ 
    … 
    "revnue_type": "CPA",
    "revenue_amount": 10,
    … 
} 

{ 
    … 
    "revenue": { 
        "type": "CPA", 
        "amount": "10.000" 
    }, 
    … 
}

Vendor Fees


{
"vendor_fees": [ 
    { 
        "id": 1, 
        "vendor": "BEESWAX", 
        "vendor_id": 8, 
        "name": "Content Fee", 
        "cpm_currency": "USD", 
        "cpm_amount": "1.00", 
        "percentage": null 
    }, 
    { 
        "vendor": "Attricon", 
        "vendor_id": 11, 
        "name": "Attribution Fee", 
        "cpm_currency": null, 
        "cpm_amount": null, 
        "percentage": "12.50" 
    } 
 ], 
}
…

SKad Network

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
{ 
    … 
    "enable_skad_tracking": true, 
    "skad_assignment_level": "creative_line_item", 
    "target_skad": true, 
    "has_skad_assignment": true, 
    … 
} 

{ 
    … 
    "skad_network": {  
        "enable_skad_tracking": true,  
        "assignment_level": "creative_line_item", 
        "target_skad": true  
    }, 
    … 
}

Segment Extension

  • For segment extension, the fields can be set as the following:
    • segment_extension_default: extension type
    • segment_extension_type_default: segment type
    • segment_extension_vendors_default: vendors
… 
{
"segment_extension_default": "person", 
"segment_extension_type_default": "1P", 
"segment_extension_vendors_default": [ 
    "TAPAD" 
   ], 
}

{ 
   … 
    "segment_extension": { 
        "extension_type": "person", 
        "segment_type": "1st_party", 
        "vendors": [ 
            { 
                "name": "TAPAD" 
            } 
        ] 
    }, 
    … 
}

Errors 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:

{
	"success": false, 
	"payload": [ 
    { 
        "id": 3867, 
        "success": false, 
        "error_code": …, 
        "message": [
        ] 
    } 
], 
"errors": [ 
     … 
	]
}

{
  "errors": { 
    … 
}, 

"warnings": { 
    … 
	} 
}

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.
{
  "name": "Line Item COPY", 
  "campaign_id": 1, 
  "type": "banner", 
  "guaranteed": false, 
  "duplicate": [ 
      "resource", 
      "flights", 
      "frequency_cap", 
      "vendor_fees", 
      "custom_event_associations", 
      "revenue", 
      "skad_network", 
      "ghost_bidding", 
      "targeting_expression", 
      "bid_modifier", 
      "delivery_modifier", 
      "creative_association" 
], 
}

Line Item Bulk Edit

  • To support editing multiple line items, we implemented a new nested endpoint named /rest/v2/line-items/bulk.
  • Based on the current design, the users can choose which fields they want to update, respectively, from the UI side, we expect different combinations of fields. Therefore, the endpoint supports the PATCH operation for this. Compared to V1, In V2, bulk updates support two request bodies.
  • Object with request parameters
    • PATCH /rest/v2/line-items/bulk?ids=1,2 - the ids request parameter should be provided

Warnings Support

  • We will introduce a new validation endpoint to provide warnings support about the bulk edit feature in our API.
  • This endpoint will be accessible through the following route: PATCH /rest/v2/line-items/bulk/validate.
  • This new endpoint will support two types of requests, similar to the "regular" /bulk endpoint:
    • List of objects in the payload.
    • One object per payload and identifiers request parameter.
  • The peculiarity of this new endpoint is that, like the /validate endpoint, we will do a redirect to the root, i.e. /bulk

Updated over 1 year ago