What is the OpenRTB deal object, and how do buyers read it?
Part of Curated deals and PMPs
The short answer
The OpenRTB deal object is the part of a bid request that states the terms of one private marketplace deal for one impression. It sits inside the Pmp object under imp, and carries the deal's id, floor, floor currency, an optional auction type override, allowed buyer seats and advertiser domains, and a flag for guaranteed deals.
Key takeaways
- In OpenRTB 2.6, deals live at imp.pmp.deals, so every impression in a request carries its own list of deals and its own private_auction flag.
- Only id is required in the Deal object; every other term is optional, so a missing field means the default applies, not that the term was agreed.
- Deal.bidfloorcur does not inherit from the impression and defaults to USD, which matters for any deal agreed in Canadian dollars.
- at set to 3 tells the bidder that bidfloor is the agreed deal price, and guar set to 1 tells it the deal is guaranteed and must be bid on.
What is the OpenRTB deal object?
Definition
- Deal object (OpenRTB 2.6)
- The object that, in the specification's words, constitutes a specific deal that was struck between a buyer and a seller. Its presence in the Pmp collection indicates that the impression is available under the terms of that deal.
The OpenRTB 2.6 specification (opens in a new tab) from IAB Tech Lab nests deal terms in two layers. Each Imp object can hold a pmp attribute, the private marketplace container for direct deals between buyers and sellers that may pertain to this impression. Inside it, the deals array holds one Deal object per agreement. The path a buyer reads in a log is imp[].pmp.deals[], so keep the impression id and the deal id together on every row of an extract.
| Attribute | Object, type and default | What the specification says |
|---|---|---|
| private_auction | Pmp; integer; default 0 | 0 means all bids are accepted; 1 means bids are restricted to the deals specified and the terms thereof |
| id | Deal; string; required | A unique identifier for the direct deal |
| bidfloor | Deal; float; default 0 | Minimum bid for this impression expressed in CPM |
| bidfloorcur | Deal; string; default USD | ISO 4217 alpha code; does not inherit from Imp.bidfloorcur; either explicitly specified or defaults to USD |
| at | Deal; integer; no default | Optional override of the overall auction type: 1 First Price, 2 Second Price Plus, 3 bidfloor is the agreed upon deal price |
| wseat | Deal; string array | Allowed list of buyer seats allowed to bid on this deal; omission implies no seat restrictions |
| wadomain | Deal; string array | Array of advertiser domains allowed to bid on this deal; omission implies no advertiser restrictions |
| guar | Deal; integer; default 0 | 1 means the deal is of type guaranteed and the bidder must bid on the deal |
| ext | Pmp and Deal; object | Placeholder for exchange-specific extensions to OpenRTB |
What does the private_auction flag do?
private_auction lives on the Pmp object, not on any single deal. The specification calls it an indicator of auction eligibility to seats named in the Direct Deals object. A value of 0, the default, means all bids are accepted, so open market bids can compete with deal bids for the same impression. A value of 1 means bids are restricted to the deals specified and the terms thereof, so only bids made under one of the listed deals are eligible.
Because the flag covers the whole Pmp container, it applies to every deal on that impression at once. When a deal sheet says private auction but logs show private_auction at 0, the deal may be set up correctly while the impression is also open to the open market, which changes who the deal's bids compete against.
Section 7.3 of the OpenRTB implementation guide (opens in a new tab) states the consequence for bidders plainly: the flag indicates whether the seller is willing to accept open market bids, and open market bids sent to a private impression auction may be rejected. A bidder therefore reads private_auction before deciding whether to add an open market bid next to its deal bids.
What do the at and guar fields mean in a deal?
The request has its own at attribute, an integer with a default of 2, where 1 means First Price and 2 means Second Price Plus. Deal.at is an optional override of that overall auction type for one deal. It accepts the same 1 and 2, plus a value the request level field does not have: 3, which the specification defines as the value passed in bidfloor is the agreed upon deal price. The spec adds that additional auction types can be defined by the exchange.
| Deal.at | Specification meaning | What bidfloor becomes |
|---|---|---|
| Absent | No override; the request's at applies | The deal's minimum bid |
| 1 | First Price | The deal's minimum bid; a winner pays its bid |
| 2 | Second Price Plus | The deal's minimum bid; the clearing price depends on the auction |
| 3 | The value passed in bidfloor is the agreed upon deal price | The price itself, not a minimum |
| Exchange defined | Additional auction types defined by the exchange | As the exchange documents it |
guar answers a different question: does the buyer have a choice? The specification says it indicates that the deal is of type guaranteed and the bidder must bid on the deal, where 1 means guaranteed and the default 0 means not. A deal can carry at 3 without guar 1, a fixed price the buyer may still pass on. guar 1 with at 3 is the pattern of a programmatic guaranteed deal.
How does wseat limit which buyers can bid?
Deal.wseat is an allowed list of buyer seats, for example advertisers or agencies, allowed to bid on this deal. The specification adds that IDs of seats and the buyer's customers to which they refer must be coordinated between bidders and the exchange a priori, and that omission implies no seat restrictions. A seat is the buyer's account identity on that exchange, so the value in wseat has to be the exact string the exchange knows the buyer by, agreed before the deal goes live.
Deal.wadomain works the same way for brands: an array of advertiser domains, such as advertiser.com, allowed to bid on this deal, with omission implying no advertiser restrictions. The bidder declares the advertiser on each bid through the Bid object's adomain field, so a mismatch between the brand's declared domain and the deal's wadomain list is one reason a valid seat still cannot win.
Confirm a seat restriction before launch
- Get your seat ID from your buying platform. Ask for the exact string the exchange uses for your seat, not an account name.
- Send it to the seller in writing. The deal's wseat list is built from what the seller receives, so a typo there blocks bids under the deal.
- List every advertiser domain. If the deal uses wadomain, give the domain each brand declares in adomain, including any regional domain.
- Check a sample request. Ask the exchange or your platform for one logged request that shows your seat in Deal.wseat for the deal id.
Which deal fields should a buyer check in logs?
OpenRTB 2.6 defines a loss notice macro, AUCTION_LOSS, whose values refer to the List: Loss Reason Codes in the OpenRTB 3.0 specification (opens in a new tab). Several codes on that list name a deal field directly, so a buyer who receives loss reasons can map a lost deal bid to the field that caused it.
| Code | Definition in the list | Field to check first |
|---|---|---|
| 4 | Invalid Deal ID | Bid.dealid against Deal.id in the request |
| 6 | Invalid Advertiser Domain | Bid.adomain against Deal.wadomain |
| 101 | Bid was Below Deal Floor | Bid price against Deal.bidfloor and Deal.bidfloorcur |
| 103 | Lost to a Bid for a Deal | Pmp.private_auction and whether your bid carried a deal id |
| 104 | Buyer Seat Blocked | Your seat against Deal.wseat or the request's bseat |
| 213 | Creative Filtered, Not Allowed in Deal | The creative format and attributes the deal allows |
Deal fields to pull for every logged request in a review
- The request id, the imp id and the Deal.id are recorded together on each row.
- Pmp.private_auction is recorded per impression, not assumed from the deal sheet.
- Deal.bidfloor is read with Deal.bidfloorcur, and an empty currency is read as USD.
- Deal.at is recorded when present, and the request's at is recorded when it is not.
- Deal.wseat contains the buyer's seat string exactly, and Deal.wadomain, if present, contains the brand's adomain.
- Bid.dealid on each bid response equals a Deal.id offered in that impression.
What does a deal object review look like on a real brief?
Fictional example
A pet food subscription brand checks its first private auction
A fictional pet food subscription company in Portland runs display beside pet care, veterinary advice and dog training articles for readers in Washington and Oregon. Its agency agreed a private auction with a publisher group: first price, a floor in USD, one buyer seat, and the brand's domain as the only allowed advertiser. Two days after launch, the trader asks the platform team for a sample of logged requests carrying the deal id.
The sample shows three things. Pmp.private_auction is 0, so the impression is also open to the open market, while the deal sheet said invitation only. Deal.at is absent, so the request's auction type applies, which happens to match the agreed first price. Deal.wadomain lists the brand's old domain, which it stopped declaring in adomain after a rebrand, and the loss notices carry code 6, Invalid Advertiser Domain.
The trader sends the seller a note naming both fields and the values the sheet agreed, and checks a fresh sample once the seller confirms the edits.
How does PlacementGraph help with the site side of a deal?
Frequently asked questions
Can one impression carry more than one deal?
Yes. The deals attribute of the Pmp object is an array, and the specification's own example offers one banner impression under two deals with different seats, floors and auction types. A bidder can bid under any deal it is eligible for, and each bid names the deal it uses in its dealid field.
Does the deal object list the websites in a curated deal?
No. A bid request describes one impression on one site or app, and the domain sits in the Site object. The list of sites in a deal is agreed outside the bid stream, for example on a deal sheet or, where both systems support it, in the inventory object of the IAB Tech Lab Deals API.
Is mincpmpersec a deal price?
No. The specification calls it a minimum CPM per second, a price floor for video or audio impression opportunities relative to the duration of the bids an advertiser may submit. It works with durfloors, which set floors by creative duration, so a longer ad faces a higher floor under the same deal.
Does OpenRTB 3.0 use the same deal fields?
Mostly, under different names. In OpenRTB 3.0 the Item object carries a deal array and a private flag, and its Deal object has id, flr, flrcur, at, wseat, wadomain and ext. It has no guar attribute, so a guaranteed term has to be confirmed some other way.
Sources
- OpenRTB 2.6 specification: Pmp, Deal, Bid and request objects (opens in a new tab)IAB Tech Lab
- OpenRTB 2.x implementation guide, section 7.3 PMP and direct deals (opens in a new tab)IAB Tech Lab
- OpenRTB specification v3.0: Deal object and loss reason codes (opens in a new tab)IAB Tech Lab
- Deal Sync API specification 1.0 (opens in a new tab)IAB Tech Lab
- SupplyChain object (opens in a new tab)IAB Tech Lab
Researched and written by PlacementGraph Research. Read how we research, source and update these pages. Corrections: diana@placementgraph.com.