Deals API for Suppliers V1 to V2 Migration Guide¶
Warning
In Q3 2024, we will begin gradually phasing out of the Deals API v1.0, starting with sunsetting the POST method.
This document describes the main differences between Deals API v1 and v2, as well as the main attention points for Suppliers to successfully migrate from v1 to v2.
The concept of revision, the main difference between two versions and supported in v2, effects every step of migration. The sections below detail how to meet the requirements of this new concept. Refer to V2 Deals Sync API for Suppliers for detailed description of revisions.
Deals API Fields Mapping¶
As part of supporting the concept of revisions in Deals API v2, all Deals API fields have been split into deals fields and revisions fields. Some fields from v1 have been changed or replaced in v2; there are also new revision specific fields. See below deal and revision fields as per v1 and v2, with notes explaining the use of those fields in v2 when necessary.
Deals Object Fields¶
v1 Field |
v2 Field |
|---|---|
buyers |
buyers |
contract_type |
contract_type |
deal_id |
deal_id |
dsp_seat |
dsp_seat |
not supported |
revisions |
Revisions Object Fields¶
v1 Deals |
v2 Revisions |
Notes |
|---|---|---|
price_type |
auction_type |
The following values are supported:
|
contact_email |
contact_email |
no changes |
creative_type |
creative_type |
The following creative types are supported as separate objects:
Specific parameters for each creative types are presented in separate objects listed in dedicated sections below. Also please refer to the GET return example for the view of the code. |
start_time |
start_time |
no changes |
end_time |
end_time |
no changes |
inventory_source |
inventory_source |
In Deals API v2 this field returns a list of values separated by a comma. When creating a deal, make sure this field is defined is a list, even if only one source is listed |
price_method |
price_method |
no changes |
ssp_ext |
ssp_ext |
no changes |
ssp_note |
ssp_note |
no changes |
guaranteed_units_purchased_count |
guaranteed_units_purchased_count |
no changes |
deal_type |
private_auction |
The following values are supported:
|
ssp_deal_status |
ssp_status |
renamed field |
price, bid_floor |
price |
The deal value depending on the auction type. FSpecifies the deal price for fixed auction, or bid floor for first-second price auction |
not supported |
targeting |
Can be used to exclude or exclude targeting criteria for the deal. Not supported by DV360 |
not supported |
number |
The revision number |
Video/Audio Creative Properties¶
Field |
Notes |
|---|---|
duration |
integer The duration of the ad in seconds, required for video/audio creative type |
duration_match |
mapped to the value of the duration field. The following values are supported:
|
skippable |
The following values are supported:
|
Display Creative Properties¶
Field |
Notes |
|---|---|
sizes |
Object, includes w and h fields with integer value type |
Deals API GET Method Changes¶
To GET the updated information on your deals from Deals API, please make sure you send your GET requests to the following endpoint:
<!-- The version is changed from v1 to v2 -->
https://my.bidswitch.com/api/v2/ssp/<seat-id>/deals/
Pagination and sorting by the updated field are supported in v2.
https://my.bidswitch.com/api/v2/ssp/ssp_id/deals/?page=1&page_size=1&sorting=updated&sorting_dir=desc
GET Return Example¶
{
"count": 43,
"next": null,
"previouis": null,
"deals": [
{
"deal_id": "some_deal_id",
"dsp_seat": "74",
"contract_type": "non-guaranteed",
"buyers": [
"abc"
],
"ssp_update_time": "2022-09-22T16:15:50.008391Z",
"dsp_update_time": null,
"status": "created",
"creation_date": "2022-09-22T16:15:49.965162Z",
"is_created_from_deals_discovery": false,
"updated": "2022-09-22T16:15:49.965220Z",
"revisions": [
{
"display_name": "Some Display Name",
"inventory_source": [
"InventorySource"
],
"contact_email": "example.example@is.com",
"guaranteed_units_purchased_count": 0,
"start_time": "2022-09-26T00:00:00Z",
"end_time": "2022-09-27T23:59:59Z",
"currency_code": "USD",
"price": "6.0000000000000000000",
"auction_type": 2,
"price_method": "cpm",
"private_auction": 0,
"creative_type": "video",
"targeting": null,
"dsp_note": null,
"ssp_note": null,
"ssp_ext": null,
"ssp_status": "active",
"dsp_update_time": null,
"ssp_update_time": "2022-09-22T16:15:50.008391Z",
"dsp_status": "created_in_dsp",
"created": "2022-09-22T16:15:50.016561Z",
"number": 1,
"dsp_revision_status_error": "",
"video": {
"duration": "30.00",
"duration_match": 2,
"skippable": 1
}
}
]
}
]
}
Deals API POST Method Changes¶
The concept of revisions itself defines the difference between POST in Deals API v1 and v2. When sending POST requests in v2, pay attention to separating the fields into those for the deal itself and those for revision. See the POST request example in v2 below.
POST Request (Creating A Deal) Example¶
{
"deals":[
{
"deal_id":"test_deal_v1",
"dsp_seat":"74",
"contract_type":"non-guaranteed",
"buyers": [
"abc",
"def"
],
"revisions":[
{
"display_name":"Test Deal v1",
"inventory_source": [
"pub-123"
],
"contact_email": "someone@example.com",
"guaranteed_units_purchased_count":23000,
"start_time": "2019-10-02T15:01:23.045123456Z",
"end_time": "2036-11-02T15:01:23.045123456Z",
"currency_code": "usd",
"price":10,
"auction_type":2,
"price_method":"cpm",
"private_auction":1,
"creative_type":"display",
"ssp_status":"active",
"number":1,
"display": {
"sizes": [
{
"w": 320,
"h": 70
}
]
}
}
]
}
]
}
Deals API PUT Method (Updating A Deal) Changes¶
To update a deal with PUT method, use the same request body as for POST method.