RTB Line Items Setup V3 — Migration Guide

Greta
Greta
  • Updated

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.

Understand Affected API Endpoints

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

New Features

  • Addition of budget flights (set budgets by time segments)

Compatibility

  • Campaigns API: No changes 

  • Orders API: Compatible with orders V2

Breaking Changes

See the request samples and field parameters that changes when migrating from V2 to V3.

Programmatic Budget

V3 introduces budgetFlights and goalType for the whole line item:

  • In V2, goalType was set by creating an object inside the budget. In V3, each budgetFlights has it's own budget and goalType applies to all budgetFlights, which means that you need to set the goalType as a global parameter for all budget flights (goalType can be either money, impressions, or clicks and can't be changed after it's set).

  • In V3, with budgetFlights, you can now set multiple flights inside each line item. Minimum one budgetFlight is required. Each budget flight needs a startDate and endDate.

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

goalType

Required

Your budget goal type, which can be either money, impressions, or clicks. Previously you had to do this by creating different objects inside a budget, the key being the indicator of the budget goal type.

This field can't be changed after a line item starts and it impacts all budget flights.

money, impressions, or clicks.

String

budgetFlights

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

startDate and endDate

Required

Line item budget start and end times are specified in the day granularity. Your campaign time zone is applied.

YYYY-MM-DD

String

budget

Required

The budget that you want to spend for the line item. The goalType specifies the units used. If money is used, the budget is specified in the campaign currency.

100

Float

periodType

Required

Unchanged from V2. Specify different period types for each budget flight.

total

String

locked

Required

Unchanged from V2. Specify whether to lock the budget for each budget flight.

false

Boolean

useParentBudget

Required

Unchanged from V2. Specify whether parent entity budget should be used for each budget flight.

false

Boolean

pacingType

Required

Unchanged from V2.

evenly

String

Line Item Schedule — Periods

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

start and end

Required

Now period start and end time needs to be provided in your defined campaign time zone.

YYYY-MM-DDTHH:MM:SS

String

Inventory Targeting—Domains and Apps

V3 no longer supports customListId in domains  and mobileApps:

  • customListId and mobileApps becomes obsolete due to the introduction of rtbTargetingListId.

  • All sub-parameters of mobileApps including storeId, appId,  appName and developerName 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

rtbTargetingListId

Required

Domains and App lists are replaced by RTB targeting lists.

0551ff0d-ebbe-4da6-a653-864981d12d02

String

templateIds

Required

Domain targeting template IDs.

33421

Integer

excludeUnknown

Required

Specify whether you want to exclude unknown domains

True

Boolean

targetingMode

Required

Specify whether you want to include or exclude domains from targeting template IDs

include or exclude

String

Buying Strategy — CPA and dCPM Pricing (non-breaking change)

In V3, pricing type for cpa changed to CamelCase:

  • netCPA is now netCpa.

  • regularCPA is now regularCpa.

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.

regularCpa, netCpa

String

dCPM

Required

dCPM models now include the AVOC model option.

vcr, dcpmPrice, viewabilityRate, avoc

String

Was this article helpful?

/
How we can make it better?

Thank you for your feedback!