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.


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.


Once a deal has been activated by the Buyer (i.e. dsp_deal_status set to active), you are prohibited from changing the value of any fields apart from ssp_deal_status

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




(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:

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


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


(Required. SSP Only) Specifies the Buyer that is party to this deal. If you have a Deal ID that should be available to multiple Buyers, add a separate row for each Buyer.


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


(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


(Required) Specifies the Advertiser/Agencies that should have access to this deal, e.g. 3566751798272. Note: Google DV360 only allow one buyer in this field and it must be their DV360 Partner ID, to obtain it you need to contact your buyer on DV360. If you want to list more than one buyer, separate each using commas e.g. agency1, advertiser2, buyer3


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


(Required. SSP Only) Supplier contact details e.g.


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


(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


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


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


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


(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


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


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


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

  • active

  • paused


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


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


(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


(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


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


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


(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


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

  • display

  • video

  • audio

  • native


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


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


(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


(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

Buyer Restrictions

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 following 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