Understanding Yahoo DSP Packages¶
Abstract¶
Describes Yahoo DSP packages, specifying how to create, read and update packages with standard HTTP POST, GET and PUT calls, with example request URLs, Body and Response JSON.
Important
For purposes of migration, it’s important to keep in mind that packages are always needed when migrating campaigns containing multiple AdGroups.
Overview¶
In Yahoo DSP, a package is an optional subcomponent of a campaign that specifies an advertising strategy. Using packages, you can group multiple lines based on common attributes, including a budget, flight dates, and goals.

This grouping provides an additional level of hierarchy between the campaign and line level, enabling you to manage multiple lines at once.
When you create packages under a campaign, you can test your strategy by comparing the performance of packages. You can then deactivate underperforming packages and keep high-performing packages active. Lines that are grouped under a package work a bit differently than lines that are not part of a package. Some of the differences are Permanence, Budgets, Start & End dates, and Targeting.
Important
Lines will not serve if a package is deactivated.
Read Campaign with package enabled¶
To read campaigns with package enabled, make a GET call to this endpoint:
GET traffic/campaigns{id}
Note
Packages can only be created under campaigns that allow packages.
Parameter |
Parameter Type |
Description |
Data Type |
Required |
---|---|---|---|---|
id |
path |
Specifies the campaign ID |
integer |
Yes |
Example Request URL¶
GET https://dspapi.admanagerplus.yahoo.com/traffic/campaigns/701134
Example Response¶
{
"response": {
"id": 701134,
"name": "TrafficAPI Single Campaign",
"createdAt": "2020-08-20T07:52:59Z",
"updatedAt": "2020-08-20T07:52:59Z",
"packageEnabled": true,
"goalValue": 5,
"accountId": 12034,
"status": "ACTIVE",
"goalType": "CTR",
"timezone": "America/Chicago",
"currency": "CAD",
"budgetSchedules": [
{
"id": 709476,
"startDate": "2020-08-22T05:00:00Z",
"endDate": "2020-08-30T05:00:00Z",
"scheduleBudget": 444.5,
"scheduleDailyBudget": 18,
"scheduleBudgetType": "SPECIFIED_AMOUNT"
}
],
"errors": null,
"timeStamp": "2020-08-20T07:56:38.729Z"
}
Create a new campaign with package enabled¶
To create a new campaign with a package enabled, make a POST request like this:
POST traffic/campaigns
Note
Once campaigns are created, you can’t update the packageEnabledattribute.
Parameters¶
All fields are specified in the body of the application/json
payload.
Example Request URL¶
POST https://dspapi.admanagerplus.yahoo.com/traffic/campaigns
Example Request Body (Package enabled)¶
{
"name": "traffic test budget - 24",
"budgetSchedules": [
{
"scheduleBudget": 444.5,
"scheduleBudgetType": "SPECIFIED_AMOUNT",
"scheduleDailyBudget": 18,
"startDate": "2020-08-20",
"endDate": "2020-09-30"
}
],
"goalType": "CTR",
"goalValue": 5,
"accountId": 2034341,
"status": "ACTIVE",
"timezone": "America/Chicago",
"currency": "USD",
"demoVendor": "COMSCORE",
"packageEnabled": true
}
Example Response¶
{
"response": {
"id": 735839,
"name": "traffic test budget - 24",
"createdAt": "2020-09-11T03:06:53Z",
"updatedAt": "2020-09-11T03:06:53Z",
"goalValue": 5,
"frequencyCapValue": 0,
"accountId": 2034341,
"status": "ACTIVE",
"packageEnabled": true
"goalType": "CTR",
"timezone": "America/Chicago",
"currency": "USD",
"demoVendor": "COMSCORE",
"budgetSchedules": [
{
"id": 745085,
"startDate": "2020-08-20T05:00:00Z",
"endDate": "2020-09-30T05:00:00Z",
"scheduleBudget": 444.5,
"scheduleDailyBudget": 18,
"scheduleBudgetType": "SPECIFIED_AMOUNT"
}
]
},
"errors": null,
"timeStamp": "2020-09-11T03:07:05.730Z"
}
Packages¶
Endpoint¶
/traffic/packages
The action that you take depends on the HTTP method and the parameters you specify. For example:
Use the
GET
method to read an existing package.Use the
POST
method to create a new package.Use the
PUT
method to update an existing package.
Resources¶
The platform provides these resources for managing and tracking packages:
packages
schedules
Package Object¶
The package object contains the following fields:
Field |
Description |
Data Type |
Create |
Update |
---|---|---|---|---|
id |
Specifies the package ID |
integer |
N/A |
Required |
name |
Specifies the unique name of the package. |
string |
Required |
Optional |
orderId |
Specifies the campaign ID. |
integer |
Required |
Optional |
status |
Specifies the current status of the package.
|
string |
Required |
Optional |
budgetType |
Specifies whether the package uses impression-based budgeting or budgeting based on US dollars for the package.
|
string |
Optional |
Optional |
supplyType |
The source of the package’s supply (Yahoo or third-party). Set to YAHOO to create Yahoo Preferred Network native packages. If you use a value other than the following, POST/PUT requests will fail with an appropriate error message.
|
string |
Required |
Optional |
schedules |
Specifies either a single budget schedule or multiple budget schedules.
|
object |
Required |
Optional |
budgetDistributorEnabled |
Specifies package budget distributor.
|
boolean |
Optional |
Optional |
mediaType |
Specifies the media type served by the package.
|
string |
Optional |
N/A 1 |
goalType |
Specifies the goal type the platform will use to optimize package performance.
|
string |
Optional |
Optional |
goalModeType |
Specifies the goal mode. The goal mode determines whether the optimizes for package delivery or package performance.
|
string |
Optional 2 |
Optional |
billingMethodType |
Specifies the billing method.
|
string |
Optional |
Optional |
marginType |
Specifies how the margin is calculated.
|
string |
Required |
Optional |
pacingModeType |
Specifies the pacing mode.
|
string |
Optional |
Optional 3 |
userFrequencyCap |
Specifies multi-layer frequency cap for the package.
|
object |
Optional |
Optional |
objective |
Specifies objective of the package.
|
string |
Optional |
Optional |
Schedules Object¶
The schedules object contains the following fields:
Field |
Description |
Data Type |
Create |
Update |
---|---|---|---|---|
id |
Specifies the ID of the budget schedule. |
integer |
N/A |
N/A |
name |
Specifies the name of the schedule.
|
string |
Required 4 |
Required |
startDate |
Specifies the start date of the package in the yyyy-MM-dd format. |
string |
Required |
Required |
endDate |
Specifies the end date of the package in the yyyy-MM-dd format. |
string |
Required |
Required |
budget |
Specifies the total budget of the package.
|
number |
Required 5 |
Optional |
dailyBudget |
Specifies the daily budget amount.
|
number |
Required 6 |
Optional |
impBudget |
Specifies the total number of impressions bought.
|
integer |
Required 7 |
Optional |
impDailyBudget |
Specifies the total number of impressions bought per day.
|
number |
Required 8 |
Optional |
dailyBudgetType |
Specifies the daily budget type.
|
string |
Required |
Optional |
language |
Specifies the language. If not specified, defaults to ENGLISH. |
string |
Optional. Required in NATIVE seats. |
Optional. Required in NATIVE seats. |
User Frequency Cap Object¶
A User Frequency Cap object defines multi-layer frequency capping for the package.
The userFrequencyCap
can be used to set up to 2 layers of frequency capping.
Field |
Description |
Data Type |
Create |
Update |
---|---|---|---|---|
frequencyCapValueDay |
Specifies the maximum number of impressions to serve per day. |
integer |
Optional |
Optional |
frequencyCapValueWeek |
Specifies the maximum number of impressions to serve per week. |
integer |
Optional |
Optional |
Note
Only frequencyCapValueDay or frequencyCapValueWeek can be set for YPN packages using the userFrequencyCap object. But Third-Party packages support all multi-level cap.
Read Package¶
To get data for a specific package, make a GET call:
GET /traffic/packages{id}
Parameters |
Parameter Type |
Description |
Data Type |
Required |
---|---|---|---|---|
id |
path |
Specifies the package ID |
integer |
Yes |
Example Request URL¶
GET https://dspapi.admanagerplus.yahoo.com/traffic/packages/10286
Example Response¶
{
"response": {
"id": 10286,
"orderId": 1405781,
"name": "package-impression-2",
"flightingEnabled": true,
"budgetType": "IMPRESSION",
"supplyType": "THIRD_PARTY",
"status": "ACTIVE",
"budgetSchedules": [
{
"id": 10520,
"name": "s1",
"impBudget": 1001,
"impDailyBudget": 11,
"dailyBudgetType": "SPECIFIED_AMOUNT",
"startDate": "2021-08-22T07:00:00Z",
"endDate": "2022-12-31T08:00:00Z"
},
{
"id": 10526,
"name": "s2",
"impBudget": 100,
"impDailyBudget": 1,
"dailyBudgetType": "SPECIFIED_AMOUNT",
"startDate": "2021-08-20T07:00:00Z",
"endDate": "2021-08-21T07:00:00Z"
}
]
},
"errors": null,
"timeStamp": "2021-08-27T18:11:30.090Z"
}
Read Packages¶
To get a filtered list of packages, make a GET call:
/traffic/packages?orderId={orderId}&query={query}&page={page}&limit={limit}&sort={sort}&dir={dir}
All of the accepted parameters are query parameters.
Parameters¶
Parameter |
Description |
Data Type |
Required |
---|---|---|---|
orderId |
Specifies the campaign ID. |
integer |
Yes |
query |
Specifies the search term.
|
string |
No |
page |
Specifies the page number. |
integer |
No |
limit |
Specifies the total number of items to return. Maximum allowed value is 100. |
integer |
No |
sort |
Specifies the column to sort by. |
string |
No |
dir |
Specifies the sort direction.
|
string |
No |
Example Request URL¶
GET https://dspapi.admanagerplus.yahoo.com/traffic/packages?orderId=1405781&limit=2&sort=id&dir=desc&seatId=2
Example Response¶
{
"response": [
{
"id": 10286,
"orderId": 1405781,
"name": "package-impression-2",
"flightingEnabled": true,
"budgetType": "IMPRESSION",
"supplyType": "THIRD_PARTY",
"status": "ACTIVE",
"budgetSchedules": [
{
"id": 10520,
"name": "s1",
"impBudget": 1001,
"impDailyBudget": 11,
"dailyBudgetType": "SPECIFIED_AMOUNT",
"startDate": "2021-08-22T07:00:00Z",
"endDate": "2022-12-31T08:00:00Z"
},
{
"id": 10526,
"name": "s2",
"impBudget": 100,
"impDailyBudget": 1,
"dailyBudgetType": "SPECIFIED_AMOUNT",
"startDate": "2021-08-20T07:00:00Z",
"endDate": "2021-08-21T07:00:00Z"
}
]
},
{
"id": 6776,
"orderId": 1405781,
"name": "package-impression-1",
"flightingEnabled": false,
"budgetType": "IMPRESSION",
"supplyType": "THIRD_PARTY",
"status": "ACTIVE",
"budgetSchedules": [
{
"id": 7004,
"impBudget": 8888,
"impDailyBudget": 88,
"dailyBudgetType": "SPECIFIED_AMOUNT",
"startDate": "2021-06-23T07:00:00Z",
"endDate": "2022-12-31T08:00:00Z"
}
]
}
],
"errors": null,
"timeStamp": "2021-08-27T18:18:34.757Z"
}
Create Package¶
To create packages, make a POST call:
POST /traffic/packages/
Parameters¶
All fields are specified in the body of :mimetype: application/json
payload.
Example Request URL¶
POST https://dspapi.admanagerplus.yahoo.com/traffic/packages
Example Response Body¶
{
"name": "package-usd-1.5",
"orderId": 1386505,
"budgetType": "CURRENCY",
"supplyType": "YAHOO",
"status": "ACTIVE",
"budgetSchedules": [
{
"budget": 999,
"name": "S1",
"dailyBudgetType": "AUTO_ALLOCATED",
"startDate": "2021-12-10T08:00:00Z",
"endDate": "2021-12-11T08:00:00Z"
}
]
}
Example: Create (Margin) oCPM Display Package with Budget distributor on¶
To create a DISPLAY line with MARGIN (oCPM) billing type, refer to the table and payload below.
Field |
Value |
Type |
---|---|---|
budgetDistributorEnabled |
true |
boolean |
mediaType |
DISPLAY |
string |
goalModeType |
HARD |
string |
goalType |
CPA |
string |
billingMethodType |
MARGIN |
string |
billingPrice |
Desired % profit margin |
number |
Example Response Body¶
{
"name": "TRAFFIC_API_PACKAGE_eEYx70Ap",
"orderId": "61",
"bidPrice": "1.5",
"goalAmount": "1.5",
"billingPrice": "2.0",
"completionThreshold": 0,
"flightingEnabled": false,
"budgetType": "CURRENCY",
"status": "ACTIVE",
"supplyType": "THIRD_PARTY",
"budgetDistributorEnabled": true,
"budgetSchedules": [
{
"budget": 100,
"dailyBudget": 20,
"dailyBudgetType": "SPECIFIED_AMOUNT",
"startDate": "2021-12-02",
"endDate": "2021-12-07"
}
],
"pacingModeType": "EVEN",
"mediaType": "DISPLAY",
"goalModeType": "HARD",
"goalType": "CPA",
"billingMethodType": "MARGIN",
"marginType": "TOTAL_BUDGET"
}
Example: Create Native Display Package with Budget distributor on and User Frequency Cap¶
To create a DISPLAY package with User Frequency Cap, refer to the table and payload below.
Field |
Value |
Type |
---|---|---|
budgetDistributorEnabled |
true |
boolean |
userFrequencyCap |
frequencyCapValueDay:10 |
boolean |
mediaType |
DISPLAY |
string |
goalModeType |
HARD |
string |
goalType |
CPA |
string |
billingMethodType |
MARGIN |
string |
billingPrice |
Desired % profit margin |
number |
Example Response Body¶
{
"orderId": 61,
"name": "TRAFFIC_TEST_PACKAGE_5OAivCTW",
"bidPrice": 0.5,
"goalAmount": 0.5,
"billingPrice": 0,
"budgetType": "CURRENCY",
"channelType": "Native",
"supplyType": "YAHOO",
"objective": "VISIT_WEB",
"status": "ACTIVE",
"budgetSchedules": [
{
"budget": 100,
"name": "CQdgy",
"dailyBudgetType": "AUTO_ALLOCATED",
"startDate": "2021-12-03",
"endDate": "2021-12-05"
}
],
"mediaType": "DISPLAY",
"goalType": "CPA",
"billingMethodType": "MARGIN",
"budgetDistributorEnabled": true,
"goalModeType": "HARD",
"marginType": "TOTAL_BUDGET",
"pacingModeType": "EVEN",
"userFrequencyCap": {
"frequencyCapValueDay": 10
}
}
Example: Create Native Display Package with Budget distributor on and Dynamic Product Ads Objective¶
To create a DISPLAY line with Budget distributor on and Objective DYNAMIC_PRODUCT_ADS, refer to the table and payload below.
Field |
Value |
Type |
---|---|---|
budgetDistributorEnabled |
true |
boolean |
mediaType |
DISPLAY |
string |
goalModeType |
HARD |
string |
goalType |
ENHANCED_CPC |
string |
billingMethodType |
CPC_WITH_MARGIN |
string |
objective |
DYNAMIC_PRODUCT_ADS |
string |
Example Response Body¶
{
"orderId": 61,
"name": "TRAFFIC_TEST_PACKAGE_Ert8aOyR",
"bidPrice": 0.0,
"goalAmount": 0.0,
"billingPrice": 0.0,
"budgetType": "CURRENCY",
"channelType": "Native",
"supplyType": "YAHOO",
"objective": "DYNAMIC_PRODUCT_ADS",
"status": "ACTIVE",
"budgetSchedules": [
{
"budget": 100.0,
"name": "lduaC",
"dailyBudgetType": "AUTO_ALLOCATED",
"startDate": "2021-12-03",
"endDate": "2021-12-05"
}
],
"mediaType": "DISPLAY",
"goalType": "ENHANCED_CPC",
"billingMethodType": "CPC_WITH_MARGIN",
"budgetDistributorEnabled": true,
"goalModeType": "HARD",
"marginType": "TOTAL_BUDGET",
"pacingModeType": "EVEN"
}
Update Package¶
To update a package, make a PUT request:
PUT /traffic/packages{id}
Partial updates are supported values of supported fields which are not in the payload will remain unchanged.
Parameters¶
The Package id is specified in the url path. All other fields are specified in the body of the application/json
payload.
Example Request URL¶
PUT https://dspapi.admanagerplus.yahoo.com/traffic/packages/6776
Example: Activate Paused Package¶
The following payload shows how to change the package status from PAUSED to ACTIVE.
Example Request Body¶
{
"status": "ACTIVE"
}
Example: Update Package Budget & Start/End Dates¶
The following payload shows how to update the total budget and start/end dates of a package.
Example Response Body¶
{
"schedules": [
{
"id": 10966,
"name": "S1",
"startDateStr": "2021-08-30",
"endDateStr": "2021-10-31",
"impBudget": 10000
}
]
}
Delete Packages¶
The DSP Traffic API does not support deletion of packages.
Create a Line under a Package¶
POST /traffic/lines
Parameters¶
All fields are specified in the body of application/json payload.
Example Request URL¶
POST https://dspapi.admanagerplus.yahoo.com/traffic/lines
Example: Create a line under a package¶
To create a line under a PACKAGE, refer to the table and payload below
Field |
Value |
Type |
---|---|---|
packageId |
Package Id |
integer |
Example Request Body¶
{
"name": "display-line-under-package-1",
"orderId": 1405783,
"packageId": 9103,
"bidPrice": 1,
"goalAmount": 1,
"maxGoal": 1,
"billingPrice": 22,
"isNativeEnabled": true,
"objective": "MAIL_SPONSORED",
"status": "ACTIVE",
"pacingModeType": "EVEN",
"mediaType": "DISPLAY",
"goalModeType": "HARD",
"goalType": "ENHANCED_CPC",
"billingMethodType": "CPC_WITH_MARGIN",
"marginType": "TOTAL_BUDGET",
"budgetType": "CURRENCY",
"schedules": [
{
"budget": 100,
"startDateStr": "2021-09-05T07:00:00Z",
"endDateStr": "2022-02-01T07:59:59Z",
"dailyBudgetType": "AUTO_ALLOCATED"
}
],
"supplyType": "YAHOO",
"language": "ENGLISH"
}
Read Lines under a package¶
To get a filtered list of lines under a package, make a GET request:
GET /traffic/lines?packageId={packageId}&query={query}&page={page}&limit={limit}&sort={sort}&dir={dir}
All of the accepted parameters are query parameters.
Parameters¶
Parameter |
Description |
Data Type |
Required |
---|---|---|---|
packageId |
Specifies the package ID. |
integer |
Yes |
query |
Specifies the search term.
|
string |
No |
page |
Specifies the page number. |
integer |
No |
limit |
Specifies the total number of items to return. Maximum allowed value is 100. |
integer |
No |
sort |
Specifies the column to sort by. |
string |
No |
dir |
Specifies the sort direction.
|
string |
No |
Example Request URL¶
GET https://dspapi.admanagerplus.yahoo.com/traffic/lines?packageId=15311&limit=1
Example Response¶
{
"response": [
{
"id": 1887077,
"name": "line 1",
"orderId": 1176518,
"bidPrice": 1.0,
"goalAmount": 1.0,
"billingPrice": 0.0,
"completionThreshold": 0.0,
"isNativeEnabled": true,
"packageId": 15311,
"objective": "PROMOTE_BRAND",
"status": "ACTIVE",
"pacingModeType": "EVEN",
"mediaType": "DISPLAY",
"goalModeType": "HARD",
"goalType": "VCPM",
"billingMethodType": "MARGIN",
"marginType": "TOTAL_BUDGET",
"budgetType": "CURRENCY",
"schedules": [
{
"id": 2324122,
"budget": 100.0,
"startDateStr": "2022-01-11T08:00:00Z",
"endDateStr": "2022-02-01T07:59:59Z",
"dailyBudgetType": "AUTO_ALLOCATED"
}
],
"feeList": [],
"conversionList": [],
"supplyType": "YAHOO",
"language": "ENGLISH"
}
],
"errors": null,
"timeStamp": "2022-01-12T00:18:15.300Z"
}