Orders Setup V2 — Migration Guide

Greta
Greta
  • Updated

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

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:

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

Was this article helpful?

/
How we can make it better?

Thank you for your feedback!