Programmatic Guaranteed Deals

In Programmatic Guaranteed Deals, you negotiate with sellers on the number of impressions that you will purchase at a fixed price. If you accept a proposal for a Programmatic Guaranteed Deal, you commit to purchasing the seller's inventory based on the negotiated terms. To learn more about your commitments and tools for monitoring your compliance, see the Help Center article describing the Programmatic Guaranteed SLA framework.

Create

Programmatic Guaranteed Deals are created when negotiations start with a request for proposal (RFP). You can initiate negotiations by sending an RFP to a seller with buyers.proposals.sendRfp. The RFP must contain programmaticGuaranteedTerms in order for the resulting proposal to be for a Programmatic Guaranteed Deal. Sellers can also send you an RFP, which will appear as a proposal in Marketplace API. Once created, you can find the proposal for the deal with buyers.proposals.list, and negotiation between you and the seller can begin.

Negotiate

Once a proposal for a Programmatic Guaranteed Deal is created, you can negotiate with the seller by adjusting the proposal and its corresponding deal until either both parties are satisfied, or the proposal is canceled. In a successful negotiation, you might perform any of the following:

  • Poll for changes to the proposal or deal: Whenever a change is made to a proposal or its corresponding deal, the proposalRevision will increment. You can use this to detect when the seller has accepted your proposal or responded with a counter-offer.
  • Patch the proposal or deal: Modify your proposal or send a counter-offer to the seller. This will increment the proposalRevision.
  • Communicate with the seller: Proposals contain notes that are visible to buyers and sellers. As an example, you can add a note to provide context about a change you made to a proposal or its deal.

Finalize and prepare for serving

When you are satisfied with a proposal and its state is BUYER_ACCEPTANCE_REQUESTED, you can accept the proposal. This finalizes the deal, which begins serving at the flightStartTime.

In order to ensure that the deal only begins serving when you have creatives prepared, we recommend you contact your Technical Account Manager to opt your Programmatic Guaranteed Deals out of this default behavior, and instead manually signal when they are ready to serve. Here's an example workflow where you manually signal when your Programmatic Guaranteed Deals are ready to serve:

  • Negotiate the proposal with the seller
  • Use Real-time Bidding API to submit creatives for review: The creatives you intend to place must be reviewed and approved for use in deals.
  • Accept the proposal: Once a proposal is accepted, the accepted deals are reflected in finalized deals.
  • Use Real-time Bidding API to retrieve the creatives submitted earlier, and confirm they are approved for use in bids on deals in Real-time Bidding: View the dealsPolicyCompliance to verify that the creatives are approved and can be placed in response to incoming deal bid requests.
    • If the creative was not approved, review the topics to determine the reason for disapproval. Adjust the creative as necessary, and patch it to initiate review once again until all issues are resolved.
  • Add all creatives that will be used to the finalized deal: We recommend adding creatives to the deal you intend to use them with before you initiate serving of the deal.
  • Manually signal that the deal is ready to serve: Once the deal is ready to serve, you will begin receiving bid requests for the deal at the configured flightStartTime, which will continue until either its flightEndTime or impressionCap is reached.

Renegotiate

After a deal is finalized, you or the seller can initiate renegotiation by modifying the proposal or its deals. During renegotiation, the finalizedDeals resource reflects the previous agreement and will continue serving based on that if possible. The deals resource instead reflects the current state of the renegotiation, which will proceed similarly to the initial negotiation.

If both you and the seller accept the renegotiated deal, it will overwrite the original finalized deal and serve based on the new agreement. Otherwise, if it is canceled, the deal will revert to its state before renegotiation began.

Bid on impressions for Programmatic Guaranteed Deals

When a Programmatic Guaranteed Deal begins serving, your Real-time Bidding integration will receive bid requests for that deal, and must bid based on the terms of the deal–for example, at a specific price for a set number of impressions over a period of time.

A given bid request may include more than one PG deal. When this happens, you are expected to respond for each deal ID submitted in the request. Fields directly relevant to Programmatic Guaranteed Deals include the following:

Google protocol OpenRTB protocol Description
BidRequest.adslot.matching_ad_data.direct_deal.direct_deal_id BidRequest.imp.pmp.deals.id Unique identifier for the deal. This will be equivalent to the resource ID of the deal as returned by Marketplace API.
BidRequest.adslot.matching_ad_data.direct_deal.deal_type BidRequest.imp.pmp.deals.ext.deal_type The type of auction, which will be set to PROGRAMMATIC_GUARANTEED, or "3" for OpenRTB JSON.
BidRequest.adslot.matching_ad_data.direct_deal.fixed_cpm_micros BidRequest.imp.pmp.deals.bidfloor Will be equivalent to the CPM of the deal that was agreed to by the buyer and seller–this would appear as fixedPrice in Marketplace API. For Programmatic Guaranteed Deals, this will override any value specified in the bid response.
BidRequest.adslot.matching_ad_data.direct_deal.publisher_blocks_overridden BidRequest.imp.pmp.deals.ext.publisher_blocks_overridden Always true for Programmatic Guaranteed Deals, meaning that excluded categories are allowed.
BidRequest.adslot.matching_ad_data.direct_deal.must_bid BidRequest.imp.pmp.deals.ext.must_bid Indicates whether buyers are required to bid on the deal. For example, if the deal is ahead of schedule, this would be set False and bidding would be optional. Otherwise, bidding is required, meaning that failing to bid may negatively impact deal delivery and inventory availability.

Pause and resume serving

You should use the buyers.finalizedDeals.pause method to pause a finalized Programmatic Guaranteed deal if you are temporarily unable to bid on it. For example, you might do this if your creative was initially approved, but was disapproved and consequently needs to be resubmitted. Note that while this will stop you from receiving bid requests for the deal, you will still need to meet any obligations that were negotiated as terms for the deal.

To resume serving the finalized deal, you can use buyers.finalizedDeals.resume.