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. - 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 itsflightEndTime
orimpressionCap
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
.