Deals Synchronisation

Deals Synchronisation is a feature built by BidSwitch to support Buyers and Suppliers sharing deal information with one another. It offers two ways by which you can share the relevant information with your trading partners. The BidSwitch Deals API, and a deals management spreadsheet which can uploaded/downloaded from the myBidSwitch UI. The deals management spreadsheet serves three main purposes:

  • Buyers and Suppliers that do not have an API integration can use the spreadsheet to synchronise deal details with each other, and use the spreadsheet as the basis for entering deal information into their own system if needed.

  • Buyers or Suppliers that have integrated using the API can automatically pull updates into their own system or push changes to BidSwitch, which will be reflected in the spreadsheet i.e. API updates will be reflected in the spreadsheet and vice versa.

  • In addition to syncing deal information, the information in the spreadsheet is used by BidSwitch to ensure that deal trading is conducted as efficiently as possible and/or troubleshoot under-performing deals.

../_images/deals-sync.png

Managing Deals in the UI

To create new deals or update existing deals, upload a version of the deals management spreadsheet with your changes. Uploaded changes are based on each Deal ID, therefore either new deals can be added or existing deals updated. Currently you cannot delete a deal, but you can set its status to paused if you do not want it to be traded.

  1. Get a copy of the spreadsheet from the Deals Synchronisation ‣ Download Deals pane. This contains all of your current deals, or you can download a blank template if you have none.

  2. Add or update the deal information for each Deal ID, making sure you include information in all of the required columns, see the Spreadsheet Columns section for an explanation of each.

  3. Save your changes

  4. Upload the changes to the Deals Synchronisation.

    • Your changes will be immediately updated in the BidSwitch UI

    • For partners with an API integration, changes will be updated in their system once they pull them from the API

    • For your partners also using a spreadsheet, the deals which you have with each will be added/update in their spreadsheet

    • Spreadsheet validation is done on a per row basis, so if you upload changes to 10 deals but have made an error in one row, the UI will show you the Deal ID of the entry you need to fix. The 9 correct entries will be updated.

Spreadsheet Columns

The Deals Synchronisation spreadsheet can be downloaded from the UI Deals Synchronisation ‣ Download Deals page. It contains for following columns which are used to manage deals.

  • You need to include information in all of the required columns for a Deal ID to be properly updated.

  • Some of the below fields are for either SSPs or DSPs only, and they are marked as such.

Excel Sheet Columns

Column

Description

deal_id

(Required) This is the deal ID which will be sent in bid requests, e.g. deal-877-twttx. Note: Do not use any of the following invalid symbols in the Deal ID:

, # % $ @ * & ? ! ` ~ " ' / \ | ( ) { } [ ]+ = ^ :

display_name

(Required) This is the name of the deal which will be shown in your partners UI, e.g. Deal name.. Only alphanumeric symbols and a period allowed.

dsp_seat

(Required. SSP Only) Specifies the BidSwitch Buyer to whom you wish to send this deal, this is the ID normally used to identify your partners and can be found on the myBidSwitch UI Demand Partners ‣ Connected Partners page, e.g. "16" is Google DV360 and "93" is The Trade Desk

ssp_name

(Required. DSP Only) Specifies the Supplier that is party to this deal.

ssp_bid_request_name

(Required. DSP Only) Specifies the Supplier name that will be passed in the bid request, this maps to the ext.ssp in the BidSwitch protocol

buyers

(Required) Specifies the Advertisers/Agencies at the dsp_seat that should have access to this deal. You should use their ID with the DSP. If you want to list more than one buyer, separate each using commas e.g. agency1, advertiser2, buyer3

For some Buyers, if you do not know the correct ID you can include a human readable version, e.g. "Brand Advertiser X" but this does not work with partners that are fully automated end-to-end.

Google DV360

Important: Google DV360 only allow one buyer in this field and it must be their top-level DV360 Partner ID.

  • To obtain the correct ID you need to contact your buyer on DV360, as only they can provide you with this ID

  • This ID cannot be their DV360 Advertiser ID, as only partner-level accounts have rights to accept deals in negotiations. More context around these different DV360 IDs/Account levels and what can be done with each can be found here.

  • DV360 Partner ID information

  • DV360 Deals Negotiation Information

Finding the correct ID
<!-- Another clue to the correct Partner ID is -->
<!-- in the Google URL which has both partner and advertiser -->
displayvideo.google.com/#ng_nav/p/<this-id>/a/1111/cs

<!-- Here the partner ID for deals sync is 123456 -->
displayvideo.google.com/#ng_nav/p/123456/a/1111/cs

The Trade Desk

The buyers field must contain a The Trade Desk Seat ID and may only contain one ID. You can find the available seat IDs in the TTD Buyer IDs tab in the spreadsheet downloaded from the myBidSwitch UI.

inventory_source

(Required) The display name of the inventory source. Should represent the seller who is actually negotiating the deal. For The Trade Desk this ID has to match with the seller_id of the inventory source as specified in ads.txt, sellers.json and the Supply Chain Object. Only alphanumeric symbols and a period, colon, underscore, space, and dash are allowed [a-zA-Z0-9-_: .], e.g. Some Publisher.

contact_email

(Required. SSP Only) Supplier contact details e.g. adops@example.com

guaranteed_units_purchased_count

(Required) For guaranteed deals, this must be an integer specifying the minimum number of impressions guaranteed by the Supplier e.g. 23000. Should be 0 if contract type is non-guaranteed.

contract_type

(Required) Specifies the contract type, the possible values are:

  • guaranteed: A deal with a guarantee around certain delivery terms

  • non-guaranteed: A deal without any delivery terms guaranteed

start_date

(Required) Specifies the start date of the deal, the format uses YYYY-MM-DD, e.g. 2019-10-02

start_time

(Required) Specifies the start time of the deal, the format uses HH:MM:SS, e.g. 15:01:23. The default time zone is UTC. The start date must be at least 1 hour in the future from the time of the update.

end_date

(Required) Specifies the end date of the deal, the format uses YYYY-MM-DD, e.g. 2019-10-02. The end date should be no later than 2036.

end_time

(Required) Specifies the end time of the deal, the format uses HH:MM:SS, e.g. 15:01:23. The default time zone is UTC

ssp_update_time

Filled by BidSwitch. Specifies the time when the inventory source was last updated, the format uses RFC3339, and the default time zone is UTC, e.g. 2019-10-02T15:01:23.045123456Z

dsp_update_time

Filled by BidSwitch. pecifies the time when the Buyer last updated the deal status, the format uses RFC3339, and the default time zone is UTC, e.g. 2019-10-02T15:01:23.045123456Z

ssp_deal_status

(Required, SSP Only) Indicates the status of the Deal on the Supplier side. Can take the following values:

  • active

  • paused

dsp_deal_status

(Required, DSP Only) Indicates the status of the Deal on the Buyer side. Can take the following values.

  • active: Deal status active. Line item assigned, valid creative assigned.

  • paused: Deal paused by buyer.

You might also see some of the following statuses in the spreadsheet if the deal has yet to be updated by a partner using an API integration.

  • pending: In some DSP this status means deal is not active and there is some action needed by the buyer to activate it.

  • created_in_bidswitch: Deal was created in BidSwitch and awaiting upload to the Buyer.

  • created_in_dsp: Deal was pushed to the Buyer and awaiting approval in the DSP UI or for them to create a line items.

  • error_in_dsp: An error occurred while pushing the deal to the Buyer.

currency_code

(Required) The currency code in ISO 4217, e.g. usd

price

(Required) Represents an amount of money for a fixed price deal, for fixed price auctions it should be equal to the bid floor, e.g. 5.22.

  • Either bid_floor or price must be a positive value

  • A non-zero price is required for a fixed price auction, for a variable price auction you may set the price to 0

bid_floor

(Required) Specifies the bid floor for this deal at auction. For fixed price deals this specifies the deal price, e.g. 5.22.

  • Either bid_floor or price must be a positive value

  • A non-zero bid_floor is required for a variable price auction, for a fixed price auction this value must match the price value

price_type

(Required) Indicated whether the price is fixed or set at auction, the valid values are:

  • fixed

  • auction

Note: If a deal has been created by an advertiser in DV360, when uploading the deal information to BidSwitch the price type must match the existing price type.

price_method

(Required) Indicates the pricing method, the only possible value is cpm

deal_type

(Required) Indicates the deal type, these are the possible values.

  • private_auction: means that the imp.pmp.private_auction request value will be 1

  • open_auction: means that the imp.pmp.private_auction request value will be 0

creative_type

(Required) Indicates the acceptable creative type for this deal, the possible values are:

  • display

  • video

  • audio

  • native

display_sizes

(Required for display) A comma separated list of Width x Height indicating the possible ad slot sizes, e.g. 320x70,320x250. Note: Don’t put a space after the separating comma.

duration

(Required for Video/Audio) The duration of the video/audio creative in seconds, e.g. 10.5

duration_match

(Required for video/audio) Indicates whether the creative duration meets the required duration, the possible values are:

  • equals_to_duration The creative duration needs to be the same as the required duration

  • less_than_or_equals_to_duration The creative duration needs to be the same as or less than required duration

skippable

(Required for video/audio) Indicates if the video/audio can be skipped, the possible values are

  • skippable: The creative must be skippable.

  • non-skippable: The creative must be non-skippable.

  • any: Can be either

dsp_note

(Optional) Passes information from the Buyer to Supplier. This is a read-only field for Suppliers and may only be changed by Buyers, e.g. "Could you lower the price from $5 to $3"

DV360 Notes

  • Each Deal ID should be unique, i.e don’t create deals using the same Deal ID for multiple different buyers

  • Once a deal has been activated by the DV360 (i.e. dsp_deal_status set to active), you may not change the value of any fields apart from ssp_deal_status

  • For DV360, once a deal has been submitted, i.e. dsp_deal_status = created_in_dsp or created_in_bidswitch, you may only update the listed fields:

  • display_name

  • contact_email

  • start_time

  • end_time

  • price_method

  • bid_floor

  • price

  • guaranteed_units_purchased_count

  • currency_code

  • skippable

  • creative_type

  • display_sizes

  • duration_match

  • duration

  • ssp_deal_status

The Trade Desk Notes

The buyers field must contain a single The Trade Desk Seat ID only. You can find the available seat IDs in the TTD Buyer IDs tab in the spreadsheet downloaded from the myBidSwitch UI.

  • The "display_name" field has a max length of 256 characters

  • The "contact_email" field has a max length of 256 characters

  • The "deal_id" field has a max length of 128 characters

  • You cannot reject a deal once it has been activated by The Trade Desk

  • With guaranteed deals the only available pricing is fixed price

  • Once created, the contract_type, price_type and buyers fields cannot be changed