API Name (Version) |
Deprecation Date |
Sunset Date |
---|---|---|
RTB Line Item Setup (V2) |
December 31, 2021 |
August 8, 2023 |
With Orders Setup V2, you can divide the orders into sections and assign different budgets to them. This provides flexible control over order delivery. For more information about budget flights, see Set Up and Manage Budget Flights.
If you have been using any Orders V1 endpoint, follow this guide to migrate V1 to V2 before the sunset date (August 8, 2023). For all the information about V2 endpoints, see Orders Setup V2.
Affected API Endpoints |
Use Case |
---|---|
Orders /v2/buyer/orders /v2/buyer/orders/{id}/active /v2/buyer/orders/{id} |
Manage orders |
See the request samples and field parameters that changes when migrating from V1 to V2.
V2 switched the authorization mechanism to OAuth. To make API requests, you need a valid bearer token with appropriate scopes. For more information, see the Authorization Guide.
Available scopes:
-
https://api.adform.com/scope/buyer.orders.readonly: Yields read only access to the API.
-
https://api.adform.com/scope/buyer.orders: Yields full access to the API.
Example header: `Authorization: Bearer <token>`
.
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 V1 Example
{ "budgetSettings": { "amount": 10.1, "goalType": "Budget", "periodType": "Daily", "pacingType": "Evenly" } }
Budget V2 Example
{ "budgetSettings": { "goalType": "Budget", "budgetFlights": [ { "startDate": "2022-10-17", "endDate": "2022-10-19", "budget": 10, "periodType": "Daily", "pacingType": "Evenly" } ] } }
Budget Field V2 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 startDate
and endDate
.
-
New accepted format:
"2022-10-17"
. -
Dates provided must be set in the campaign time zone.
startDate and endDate V1 Example
{ "startDate": "2022-10-23T00:00:00+03:00", "endDate": "2022-10-17T00:00:00+03:00" }
startDate and endDate Example
{ "startDate": "2022-10-17", "endDate": "2022-10-23" }
startDate and endDate V2 parameters
Name |
Scope |
Description |
Example Values |
Type |
---|---|---|---|---|
|
Required |
Time and time zone have been removed as granularity of this field is 1 day. |
YYYY-MM-DD |
String |
impressionCapping
has been renamed to impressionCappings
to reflect that it's an array.
Impression Capping V1 Example
{ "impressionCapping": [ { "type": "Frequency", "impressions": 1, "period": { "type": "Days", "duration": 1 } } ] }
Impression Capping V2 Example
{ "impressionCappings": [ { "type": "Frequency", "impressions": 1, "period": { "type": "Days", "duration": 1 } } ] }
Impression Capping V2 Parameters
Name |
Scope |
Description |
Example Values |
Type |
---|---|---|---|---|
|
Optional |
|
|
Array |