API Name (Version) |
Deprecation Date |
Sunset Date |
---|---|---|
RTB Line Item Setup (V2) |
December 31, 2021 |
August 8, 2023 |
With RTB Line Items Setup V3, you can divide the line items into sections and assign different budgets to them. This provides flexible control over line item delivery. For more information about budget flights, see Set Up and Manage Budget Flights.
If you have been using any RTB Line Item V2 endpoint, follow this guide to migrate V2 to V3 before the sunset date (August 8, 2023). For all the information about V3 endpoints, see RTB Line Items Setup V3.
Affected Endpoints |
Use Case |
---|---|
DeviceAndCookieIdLists /v2/buyer/rtb/deviceandcookieidlists |
Upload device and cookie ID list for retargeting |
DomainLists /v2/buyer/rtb/domainlists |
Upload domain lists for inclusion or exclusion lists for inventory targeting |
IPRangeLists /v2/buyer/rtb/iprangelists |
Upload IP ranges for retargeting |
LineItems /v2/buyer/rtb/lineitems /v2/buyer/rtb/lineitems/{id} /v2/buyer/rtb/lineitems/{id}/deleted /v2/buyer/rtb/lineitems/{id}/paused /v2/buyer/rtb/lineitems/{id}/labels /v2/buyer/rtb/lineitems/{id}/domains /v2/buyer/rtb/lineitems/{id}/inventories |
Manage programmatic line items |
See the request samples and field parameters that changes when migrating from V2 to V3.
V3 introduces budgetFlights
and goalType
for the whole line item:
In V2,
goalType
was set by creating an object inside the budget. In V3, eachbudgetFlights
has it's own budget andgoalType
applies to allbudgetFlights
, which means that you need to set thegoalType
as a global parameter for all budget flights (goalType
can be eithermoney
,impressions
, orclicks
and can't be changed after it's set).In V3, with
budgetFlights
, you can now set multiple flights inside each line item. Minimum onebudgetFlight
is required. Each budget flight needs astartDate
andendDate
.
In addition, Amount
is renamed budget
.
Budget V2 Example
{ "budget": { "money": { "amount": 100.5, "pacingType": "evenly", "periodType": "total", "locked": false }, "useParentBudget": false } }
Budget V3 Example
{ "budget": { "goalType": "clicks", "budgetFlights": [ { "startDate": "2022-10-18", "endDate": "2022-10-18", "budget": 100, "periodType": "total", "locked": false, "useParentBudget": false, "pacingType": "evenly" } ] } }
Budget Field V3 Parameters
Name |
Scope |
Description |
Example Value |
Type |
---|---|---|---|---|
|
Required |
Your budget goal type, which can be either This field can't be changed after a line item starts and it impacts all budget flights. |
|
String |
|
Required |
Now allows for multiple budgets per entity, so this is an array of budgets. Budget flights can't overlap with each other. |
Multiple budget flight objects |
Object |
|
Required |
Line item budget start and end times are specified in the day granularity. Your campaign time zone is applied. |
|
String |
|
Required |
The budget that you want to spend for the line item. The |
|
Float |
|
Required |
Unchanged from V2. Specify different period types for each budget flight. |
|
String |
|
Required |
Unchanged from V2. Specify whether to lock the budget for each budget flight. |
|
Boolean |
|
Required |
Unchanged from V2. Specify whether parent entity budget should be used for each budget flight. |
|
Boolean |
|
Required |
Unchanged from V2. |
|
String |
V3 no longer supports the offsets when assigning time in periods. New accepted format is "2017-01-01T12:00:00"
.
Periods V2 Example
{ "periods": [ { "start": "2017-01-01T12:00:00+00:00", "end": "2017-01-11T12:00:00+00:00" } ] }
Periods V3 Example
{ "periods": [ { "start": "2017-01-01T12:00:00", "end": "2017-01-11T12:00:00" } ] }
Periods V3 parameters
Name |
Scope |
Description |
Example Values |
Type |
---|---|---|---|---|
|
Required |
Now period start and end time needs to be provided in your defined campaign time zone. |
|
String |
V3 no longer supports customListId
in domains
and mobileApps
:
customListId
andmobileApps
becomes obsolete due to the introduction ofrtbTargetingListId
.All sub-parameters of
mobileApps
includingstoreId
,appId
,appName
anddeveloperName
are also no longer supported.
Domains V2 Example
{ "domains": { "includeRule": { "customListId": "", "templateIds": [ 33421 ] }, "excludeUnknown": true } }
Domains V3 Example
{ "domains": { "includeRule": { "rtbTargetingListId": "", "templateIds": [ 33421 ] }, "excludeUnknown": true } }
Apps V2 Example
{ "mobileApps": [ { "storeId": 1, "appId": "97cfddd5-981c-4ec9-beda-00efc143c8e0", "appName": "Facebook", "developerName": "Meta" } ], "customListId": "customListId", "targetingMode": "include", "excludeUnknownApps": true }
Apps V3 Example
{ "rtbTargetingListId": "d6467f8d-52aa-43be-b39d-3ad42399dba4", "targetingMode": "include", "excludeUnknownApps": true }
Domains and Apps V3 Field Parameters
Name |
Scope |
Description |
Example Values |
Type |
---|---|---|---|---|
|
Required |
Domains and App lists are replaced by RTB targeting lists. |
|
String |
|
Required |
Domain targeting template IDs. |
|
Integer |
|
Required |
Specify whether you want to exclude unknown domains |
|
Boolean |
targetingMode |
Required |
Specify whether you want to include or exclude domains from targeting template IDs |
|
String |
In V3, pricing type for cpa
changed to CamelCase:
netCPA
is nownetCpa
.regularCPA
is nowregularCpa
.
V3 introduces avoc
in dCPM subtype.
Pricing — CPA Type V2 Example
{ "pricing": { "cpa": { "price": 1.0000, "maxBidPrice": 1.0000, "optimization": "allConversions", "interactionType": "postClick", "type": "regularCpa" } } }
Pricing — CPA Type V3 Example
{ "pricing": { "cpa": { "price": 1.0000, "maxBidPrice": 1.0000, "optimization": "allConversions", "interactionType": "postClick", "type": "regularCPA" } } }
Pricing — dCPM Subtype V3 (avoc)
{ "pricing": { "dcpm": { "price": 1.0000, "maxBidPrice": 1.0000, "type": "avoc" } } }
Pricing — CPA Type and dCPM Subtype Field Parameters
Name |
Scope |
Description |
Example Values |
Type |
---|---|---|---|---|
CPA |
Required |
Capitalization of enum values changed. |
|
String |
dCPM |
Required |
dCPM models now include the AVOC model option. |
|
String |