Orders Setup V2 — Migration Guide

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.

Understand Affected API Endpoints

Affected API Endpoints	Use Case
Orders /v2/buyer/orders /v2/buyer/orders/{id}/active /v2/buyer/orders/{id}	Manage orders

Affected API Endpoints

Use Case

Orders

/v2/buyer/orders

/v2/buyer/orders/{id}/active

/v2/buyer/orders/{id}

Manage orders

New Features

Addition of budget flights (set budgets by time segments)

Breaking Changes

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

Authorization

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

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 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
`goalType`	Required	Your budget goal type, which can be either `budget`, `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

Order Schedule — startDate and endDate

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
`startDate` and `endDate`	Required	Time and time zone have been removed as granularity of this field is 1 day.	YYYY-MM-DD	String

Programmatic Budget — Impression Capping

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
`impressionCappings`	Optional	`impressionCapping` was renamed to `impressionCappings` to reflect that it's an array	`2`	Array

Orders Setup V2 — Migration Guide

Understand Affected API Endpoints

New Features

Breaking Changes

Authorization

Programmatic Budget

Order Schedule — startDate and endDate

Programmatic Budget — Impression Capping

<%= previousTitle %>

<%= nextTitle %>

In this article

What's New

<% if (!block.description) { %> <%= block.name %> <% } else { %> <%= block.name %> <% } %>

Get in touch

<% if (!block.description) { %> <%= block.name %> <% } else { %> <%= block.name %> <% } %>

Still have questions?

Categories

Toggle navigation menu

<%= category.name %>

Get in touch

<% if (!block.description) { %> <%= block.name %> <% } else { %> <%= block.name %> <% } %>