A Deal represents a segment of inventory, terms, targeting details, and other information for serving ads. You can include one or more deals in a Proposal to negotiate with publishers.

Deal types

There are three types of deals you can use in negotiations:

Life cycle

This section explains the different stages in the life cycle of a deal.

Create proposals

Buyers can start negotiations by sending a request for proposal (RFP), where the deal type is specified by preferredDealTerms or programmaticGuaranteedTerms in the request body. These deal types require the flightStartTime and flightEndTime fields.

To send a proposal, you must refer to a publisher by their PublisherProfile.

Negotiate with publishers

During this stage, you do the following:

  • Update the proposal and its corresponding deals.
  • Poll for updates from the publisher.
  • Decide when to accept the terms of the proposal.

You can patch a proposal or deal to make changes. Updating a proposal increments proposalRevision.

Cancel negotiation

What happens when you cancel negotiation for a proposal and its corresponding deals depends on whether the proposal has a finalized proposalRevision.

If no finalized proposalRevision exists, the proposal’s state is TERMINATED, and the proposal is no longer available to negotiate. In that case, you must send a new proposal to resume negotiating with the publisher.

Otherwise, the proposal and its deals revert to the last finalized proposalRevision.

You can't cancel proposals for private auction deals with the Marketplace API. You can archive private auction deals in the Authorized Buyers Marketplace UI.

Finalize deals

After both parties accept a proposal, the deals in the proposal are considered finalized. You can use the buyers.finalizedDeals resource to manage your finalized deals.

If a proposal is modified before both parties accept, both parties have to accept the new revision before the deals in the proposal are considered finalized.

Serve finalized deals

After a deal is finalized, it appears in bid requests based on the time range specified by flightStartTime and flightEndTime. If no flight times are specified (only possible for private auction deals), the deal serves indefinitely.

Deals begin serving as soon as possible after they're finalized. Serving usually begins at the specified flightStartTime.

If you want to opt out of the default serving behavior and manually indicate when you're ready to start receiving bid requests, ask your Technical Account Manager to enable you to manually set deals as ready to serve.

Google recommends that you manually begin serving for programmatic guaranteed deals if you need to prepare creatives for these deals so you can ensure that the creatives are reviewed and ready to be submitted in bids for Real-time bidding before the deals begin to serve. After you add the creatives you want to place with a programmatic guaranteed deal, we recommend that you verify the creatives associated with the deal before you begin serving.

In bid requests, deals can be represented by either of the following fields, depending on the protocol:

  • Google: BidRequest.adslot[].matching_ad_data[].direct_deal[].direct_deal_id
  • OpenRTB: BidRequest.imp[][].id

You can pause and resume preferred deals and programmatic guaranteed deals after they start serving. Pausing a deal causes you to stop receiving bid requests for that deal until you resume the deal.

Only the publisher can pause private auction deals.

Start renegotiation

Buyers and publishers can start renegotiation for finalized preferred deals and programmatic guaranteed deals. You can begin renegotiation by modifying a proposal or its deals. You can then renegotiate until both parties accept the changes, or the renegotiation is canceled.

If accepted, the proposal’s revised deals replace the existing finalized deals and serve based on the updated terms.

If canceled, the proposal and its deals revert to the last finalized proposalRevision.

During renegotiation, previously finalized deals continue to serve. You can continue to view your finalized deals and their latest proposal revision.

Renegotiation isn’t supported for private auction deals.

End serving

Finalized deals for all supported deal types have their dealServingStatus set to ENDED after the deal stops serving. Here are some sample conditions that might end a deal's serving period:

  • The time period set in flightStartTime and flightEndTime passes. This is common for preferred deals or programmatic guaranteed deals, because these fields are required.
  • The programmatic guaranteed deal’s impressionCap has been reached.

Private auction deals that don’t define a flightStartTime and flightEndTime can serve indefinitely.