Deals Management

Deals Management 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 User Interface. The previous spreadsheet options is still supported and you can can uploaded/downloaded it using the Bulk Management option. The various deals management options serve these main purposes:

  • Buyers and Suppliers that do not have an API integration can use the spreadsheet/UI to synchronise deal details with each other, and use the myBidSwitch UI 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/UI i.e. API updates will be reflected in the spreadsheet/UI 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.

  • The UI provides a single overview where you can view and manage all of your deals trading through BidSwitch.

  • You can monitor Deal Statuses and identify deals that need troubleshooting

  • Troubleshooting deals has been improved by allowing you to filter deals by errors or actions needed, as well as improving error messages.

  • Initiating and negotiating deals is also more robustly supported through deal revisions.

../_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 Management ‣ Bulk Management 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 in the spreadsheet.

  4. Upload your changes.

    • 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 processed.

Monitoring Performance and Statuses

The negotiation, activation, and trading statuses of a deal’s lifecycle can also be monitored in the UI. Each deal can exist in a different status with each party, e.g. proposed by the Supplier but in review at the Buyer. Similarly, a Supplier may send sufficient requests to abide by the deal terms but the Buyer may have targeting settings that drop the majority of requests causing confusion as to its under delivery.

Negotiating

On the Buyer side, to negotiate a deal open the Revision Request messaging field. This lets you send a note to your trading partner to address any changes you may want. Each note is associated with a particular deal, to open this field use the Deals Management –> <Individual Deal Page> –> Request Change button.

Once any requested changes have been made to a deal, a new revision is created and the details of it need to be accepted by both sides anew. See the Actual Revision field to identify the revision currently trading.

On the Supplier side, to negotiate a deal you can edit the fields in the UI and once saved the changes generated an updated revisions that will be sent to the Buyer to review.

Troubleshooting

To troubleshoot any issues and keep deals trading smoothly, the Deals Management UI displays the relevant details of each deal. From the Deals Management page, use the following statuses to identify how deals are trading.

  • Action Required Click into the individual deal page to check its Delivery Status. This field should contain a message identifying something that needs to be rectified. The steps needed to address each possible problem are outlined in the Deals Insights FAQ section, or you may find the answer to an issue in the Quick Actions table.

  • Active The deal is trading as expected, click into the individual deal page to check its performance in more detail.

  • Archived Indicates that the deal ended more than 2 months ago.

  • Broken Click into the individual deal page to check its Delivery Status. This field should contain a message identifying the issue The steps needed to address each possible problem are outlined in the Deals Insights FAQ section.

  • Conditionally Completed The deal has passed its end date but the full set of terms wasn’t reached, e.g. spend, imps or clicks etc. To resolve this state, extend the end date so that the deal has sufficient time to hit its targets.

  • Created in BidSwitch The deal has been successfully created in BidSwitch and is ready to be synced to the Buyer system.

  • Paused One of the parties paused the deal.

  • Pending The deal is pending review by one of the parties.

  • Planned The deal is accepted by both sides and waiting for the start date.

  • Review The deal revision is being reviewed.

Delivery Status Quick Actions

The Deals User Interface displays the status of each deal, for each of the possible statuses indicating a problem, you can try to alleviate it using the following quick fixes, for more comprehensive details see the Deals Insights FAQ section.

Deal Statuses and Quick Actions

Status

Action

No Trading

Ensure that the deal has been accepted and set to Active by both sides.

Too Few Avails

Not enough avails for the deal to trade optimally, see the troubleshooting section to check for issues such as geo targeting or other traffic filters that may limit supply.

Too Few Requests Sent

See the troubleshooting section in the UI, or review the below FAQ for

Too Few Yes Bids

The Buyer is not bidding on requests,

Too Few Impressions

Investigate the deal performance

Too Low eCPM

Investigate the bidder performance

The Deal is out of time

The end date of the deal has passed, to restart the deal adjust its time range.

Inactive

Set the deal to an active state.

Paused

Set the deal to an active state.

The Deal is archived

Deals are archived after 2 months of inactivity, to reactivate the deal adjust its time range and ensure its set to active.

Spreadsheet Columns

The Deals Management spreadsheet can be downloaded from the UI Deals Management ‣ Bulk Management 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

revision_id

This is a read-only field generated by BidSwitch. When a Supplier changes the value of any field(s), excluding the ssp_deal_status field, the revision_id is incremented. This field displays the latest revision logged with BidSwitch and indicates the total number of revisions the deal has been through.

deal_id

(Required) This is the deal ID which will be sent in bid requests, e.g. "deal-877-twttx". Note: It has a maximum character limit of 256 and you cannot use any of the following symbols in the Deal ID, as doing so will result in request invalidation:

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

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. At least 1 ID is required.

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 ads.txt ID for the publisher(s) from whom the deal inventory is sourced. This helps to ensure the ads.txt authorization status is correct for deals verification on both ends within real time trading and during negotiations. Only alphanumeric symbols and a period, colon, underscore, space, and dash are allowed [a-zA-Z0-9-_: .], e.g. pub-id-1642, pub-id-1776. Each inventory source name has a maximum length of 250 characters.

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

  • rejected

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.

  • rejected: Deal has been rejected.

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

  • The inventory_source field has a maximum limit of 250 characters.

  • Once a deal has been activated by the DV360 (i.e. dsp_deal_status set to active or paused), you may only change the value of the following fields:

    • If the contract_type is non-guaranteed: price, bid_floor, start_time, end_time, and ssp_deal_status

    • If the contract_type is guaranteed you may only update the ssp_deal_status field

  • 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

    • price_method

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