What is a deal ID, and how does it travel through a bid request?
Part of Curated deals and PMPs
The short answer
A deal ID is a unique string that names one programmatic deal between a seller and a buyer. The seller side creates it in the system that sells the inventory, the buyer targets it in a buying platform, and each bid request the deal applies to carries it, so the winning bid and reports point back to the agreed terms.
Key takeaways
- In OpenRTB 2.6 the deal ID sits in the Deal object inside the impression's Pmp object, and a bid made under the deal returns it in the dealid field.
- OpenRTB's implementation guide says a deal ID should be treated as a targeting token on orders, line items or campaigns, not tied to a buyer seat or an advertiser.
- A curated deal can have two identifiers: the ID in the system where the deal was entered and the curator's own ID, and the buyer should bid with the origin system's ID.
- A deal ID does not prove who is authorized to sell an impression; that check runs through ads.txt, sellers.json and the SupplyChain object.
- Deal ID failures can happen at hand-off: a mistyped ID, an ID attached to the wrong object, or bid requests that arrive before the ID exists.
What exactly is a deal ID in programmatic buying?
Definition
- Deal ID
- A string, unique within the system that issued it, that identifies one agreement between a seller and one or more buyers. Exchanges attach it to eligible impressions and buyers target it, so both sides can match bids, wins and spend to that agreement.
The idea predates today's curated deals. In 2013 the IAB's Programmatic and Automation paper (opens in a new tab) described the deal ID as an additional parameter passed in a bid request and bid response, a unique string of characters used as an identifier for buyers and sellers. It added that buyer and seller decide what the string stands for, such as priority, transparency, floor pricing or data.
The current OpenRTB 2.6 specification (opens in a new tab) keeps that role. Its Deal object has one required attribute, id, described as a unique identifier for the direct deal. Every other attribute, such as a floor, allowed seats or a guaranteed flag, is optional. The string points to the deal record held by the selling system and to the agreement behind it.
How does a deal ID move between the exchange and the buyer's platform?
In a bid request, deals live inside each impression. OpenRTB 2.6 describes the Pmp object as the private marketplace container for direct deals that may pertain to that impression, and each Deal object in its deals array means the impression is available under that deal's terms. The Pmp object also holds private_auction: 1 restricts bids to the listed deals, 0 lets open market bids compete too.
In the bid response, the Bid object has a dealid field, defined as a reference to the deal.id from the bid request when the bid pertains to a private marketplace direct deal. That echo is what ties a win to the agreement and its terms. The implementation guide warns that open market bids sent to a private auction may be rejected, so a bid meant for a deal has to carry the ID.
| Place | Field or setting | Who reads it |
|---|---|---|
| Bid request | imp.pmp.deals[].id, one entry per eligible deal | The buyer's bidder, to find line items targeting that deal |
| Bid response | seatbid.bid.dealid, echoing the request's ID | The exchange, to apply the deal's terms and priority |
| Buying platform | The deal or inventory source record, entered once | The trader, who targets it in line items or campaigns |
| Deals API message | deal.id in the origin system's namespace | The receiving platform, when the seller pushes deal terms |
| Curation record | curation.cdealid in the curator's namespace | The curator's own reporting and invoicing |
| Delivery reports | Deal ID or deal name dimension | Both sides, to reconcile impressions and spend |
What does OpenRTB recommend for bidding on a deal ID?
Section 7.3 of the OpenRTB implementation guide (opens in a new tab) sets out best practice for deal bidding. A bidder should match its bids against each deal in the request, append the best matching deal bids, and, when private_auction is off, add open auction bids as well. The guide calls 1+1 bidding the minimum viable approach and M+N bidding the ideal, because returning a single bid when both a deal bid and an open bid are valid creates problems.
The same section recommends a deal ID whenever an auction may be awarded on something other than price alone, and whenever a seat gets a preferential floor. It then lists anti-patterns that platforms have run into.
| Anti-pattern | What goes wrong | What a buyer can ask |
|---|---|---|
| Running deal bids through an internal price auction | Deal bids are sorted by price and cut, so the deal does not get the bids it needs to fill | Does the platform submit every matching deal bid, not only the highest one? |
| Attaching the deal ID to the wrong object | Tied to a seat, the ID runs in too many campaigns; tied to an advertiser, it can limit that advertiser to one deal | Is the ID targeted at the order, line item or campaign level? |
| Misreading the private_auction flag | Open market bids are sent to a private impression and rejected | Does the bidder read private_auction before adding open bids? |
| Treating seat IDs as a filter on open impressions | Open inventory loses buyers it was meant to welcome | Are seat restrictions applied only to the deal they belong to? |
| Silently discounting deal bids for margin | A fee taken from the bid pushes it under the deal price, so the deal fails | Is any fee or margin applied above the agreed deal price? |
Can one deal have more than one ID?
Yes, in curated deals. IAB Tech Lab's Deals API specification (opens in a new tab) defines deal.id as a unique identifier in the origin's namespace, where the origin is the system with the interface where the deal was first entered, typically an SSP. Its Curation object adds cdealid, a unique identifier for the deal in the curator's namespace. So a curator's dashboard and an exchange's dashboard can show different strings for the same package.
The specification settles which one to bid on: the deal.id in the OpenRTB request, taken from the origin system that pushed the deal. A buyer who types a curator's internal reference into the buying platform targets an ID that does not appear in bid requests.
What can a deal ID not tell a buyer?
A deal ID says which agreement an impression is offered under. It does not show that the seller is authorized, which sites are inside the deal, or that the impression matches the deal sheet. Those are separate checks.
On authorization, the Deals API specification is direct: it is not possible to validate that the party selling the inventory has been authorized without a site ID or app bundle that matches the publisher's ads.txt file, and deal IDs receiving requests without that information should be used rarely and closely monitored. It points to the OpenRTB SupplyChain object (opens in a new tab) for supply chain validation, and says to proceed with extreme caution when that object is unavailable. Our supply path guide covers how ads.txt and sellers.json are read together.
What to verify alongside the deal ID
- The domains in served impressions match the site list the deal was built from.
- The bid requests carry a site domain or app bundle that can be matched to the publisher's ads.txt file.
- The SupplyChain object is present, and its nodes match sellers listed in the exchanges' sellers.json files.
- The buying platform applies its own targeting for the agreed terms instead of relying on the seller's setup alone.
Why does a valid deal ID still deliver nothing?
Deal hand-offs are one place deal ID problems start, because the same terms are typed into more than one system. IAB Tech Lab's Deals API specification (opens in a new tab) was written to reduce that manual entry: its stated goal is to decrease manual entry of deal information across systems by letting the origin system push the terms to the system that will deliver the deal, for review and acceptance. Tech Lab finalized version 1.0 on February 6, 2026, after a public comment period that ran until January 31, 2026. The specification still tells buyers to validate live bid requests against those terms.
Buying platforms expose some of those failure points. Display & Video 360's Troubleshooter (opens in a new tab) reports, for a chosen deal, the total available requests, bid responses, impressions won and win rate, and lists filtered impressions by reason. Two of its reasons are specific to deals and supply: requests sent before the deal was created, typically because they arrived before the deal ID had been generated, and requests from unauthorized sellers under ads.txt.
Diagnose a silent deal ID in this order
- Confirm the string. Compare the ID in the buying platform with the seller's confirmation, and confirm it is the origin system's ID, not a curator's or a proposal reference.
- Check for bid requests. No available requests can mean the deal is not active yet, is set up for another seat, or covers inventory that is not selling.
- Check the targeting object. The ID must be targeted by an active line item or campaign, not sitting in a library with nothing pointing to it.
- Check filtering. Look for requests removed before bidding, such as unauthorized sellers or requests that predate the deal.
- Check the price path. Confirm that fees or margins are not taking the bid under the deal price, which the implementation guide lists as an anti-pattern.
What does a clean deal ID hand-off look like?
Fictional example
A home solar installer's deal in the US Southwest
A fictional residential solar installer wants display ads beside home energy, electricity bill and home improvement content for readers in California, Arizona and Nevada. Its agency approves a site list and asks an exchange to package it as a private auction priced in USD.
The exchange sends back one deal ID with the seat allowed. The trader records it in a hand-off note with the exchange, the go-live date and the list version, and notes that a curator's internal reference exists but is not to be targeted.
The trader adds the ID to one line item with targeting for the three states, so the buying platform enforces the geography itself. On day two the platform shows bid requests but few bids; a fee is pushing bids under the floor, so the trader corrects the bid and logs the change.
How does PlacementGraph prepare what a seller needs to issue a deal ID?
Frequently asked questions
Is a deal ID the same as a line item or insertion order ID?
No. A line item or insertion order ID belongs to the buyer's own platform and describes how the buyer spends. A deal ID comes from the seller side and names the agreement the inventory is offered under. A line item targets one or more deal IDs, and OpenRTB's implementation guide recommends attaching the deal ID at that level.
Can several line items or campaigns target the same deal ID?
Yes, because the implementation guide treats a deal ID as a targeting token for orders, line items or campaigns. Display & Video 360, for example, lets other line items target a Programmatic Guaranteed deal ID through cross campaign optimization. Seat and advertiser domain limits on the deal still apply to every line item.
Does a deal ID expire?
The ID lives as long as the deal record. In the Deals API, the seller can mark a deal active, paused, pending, complete or archived, and an archived deal cannot be active again. Evergreen deals leave the end date blank. A buyer still targeting an ended deal will see no bid requests for it.
Can a deal ID appear on impressions that are also open to the open auction?
Yes. When the Pmp object's private_auction flag is 0, all bids are accepted, so deal bids and open market bids compete on the same impression. OpenRTB's implementation guide also describes deal IDs used as package markers on open inventory, where the winner is still decided by bid price.
Sources
- OpenRTB 2.6 specification (opens in a new tab)IAB Tech Lab, OpenRTB repository
- OpenRTB 2.x implementation guide, section 7.3 PMP and Direct Deals (opens in a new tab)IAB Tech Lab, OpenRTB repository
- Deal Sync API Specification, version 1.0 (opens in a new tab)IAB Tech Lab, deal-api repository
- Programmatic and Automation: The Publishers' Perspective (opens in a new tab)IAB, September 2013
- SupplyChain object (opens in a new tab)IAB Tech Lab, OpenRTB repository
- Cross Campaign and Cross Advertiser Optimization (opens in a new tab)Display & Video 360 Help
- Troubleshoot your deals and line items (opens in a new tab)Display & Video 360 Help
Researched and written by PlacementGraph Research. Read how we research, source and update these pages. Corrections: diana@placementgraph.com.