Marketplace resources

The Ad Exchange Buyer API II enables buyers to access Marketplace programmatically to discover inventory and negotiate deals with publishers.

Supported deal types

Deal types supported for Marketplace in the Ad Exchange Buyer API II include:

• Preferred Deals
• Private Auction Deals
• Programmatic Guaranteed Deals

You can read more about these and other Marketplace concepts in the Help Center documentation.

Note: Legacy Preferred Deals created by negotiation with former Ad Exchange Seller publishers differ slightly from those negotiated with Google Ad Manager publishers. Legacy Preferred Deals can no longer be created, and none will be presented in this guide. For more information about Legacy Preferred Deals, contact your Technical Account Manager.

Find publishers

The publisherProfiles resource can be used to retrieve details about either individual or multiple publishers participating in the Marketplace.

Note: Not all publishers returned by the publisherProfiles resource are guaranteed to participate in all deal types. If you attempt to create a proposal for a deal type in which the publisher can't participate, an error response will be returned.

Here's an example using the publisherProfiles.list method to retrieve details about multiple partners. Note that a small pageSize is set for brevity; the maximum response size would otherwise be determined by the API endpoint.

View the request

GET https://adexchangebuyer.googleapis.com/v2beta1/accounts/12345678/publisherProfiles?pageSize=3

The server responds with a 200 OK HTTP status code and the requested number of publisher profiles:

View the response

{
  "nextPageToken": "CBMQhMP01ezH3ZIYgMP33eyH4BL=",
  "publisherProfiles": [{
      "displayName": "Mars Federation Network",
      "programmaticDealsContact": "[e-mail]",
      "directDealsContact": "[e-mail]",
      "overview": "Mars Federation Network is a news organization based in
      Newer York, Mars. We produce high quality journalism across a diverse
      range of topics, both locally and across the galaxy.\n",
      "buyerPitchStatement": "Mars Federation Network is Mars's most - trusted
      news source. Your campaign can be associated with our high quality
      journalism and a brand that Martians trust.\n ",
      "seller": {
        "accountId": "123456789"
      },
      "googlePlusUrl": "https://plus.google.com/+MFN/posts",
      "samplePageUrl": "https://www.mfn.mf/ ",
      "topHeadlines": ["Respected journalism", "Planetary and galactic reach"],
      "logoUrl": "//www.gstatic.com/adx/customerlogos/4442216451/0/1455682298174.jpg",
      "publisherProfileId": "PP99999"
    },
    {
      "displayName": "MarMar",
      "programmaticDealsContact": "[e-mail]",
      "directDealsContact": "[e-mail]",
      "overview": "MarMar is the largest social network on Mars, reaching over
      1 billion daily active users.\n",
      "buyerPitchStatement": "Most active social network on Mars, with reach on
      multiple platforms.\n",
      "seller": {
        "accountId": "987654321"
      },
      "googlePlusUrl": "https://plus.google.com/+MarMar",
      "samplePageUrl": "https://marmar.mf",
      "topHeadlines": ["Largest Mars social network", "Destination for Martians
      across the globe"],
      "logoUrl": "//www.gstatic.com/adx/customerlogos/8421357443/1/1544933921459.jpg",
      "publisherProfileId": "PP11111"
    },
    {
      "displayName": "MarsAcademy",
      "programmaticDealsContact": "[e-mail]",
      "directDealsContact": "[e-mail]",
      "overview": "MarsAcademy offers the largest repository of academic
      journals published on Mars, covering a broad range of research topics.\n",
      "buyerPitchStatement": "Associate your brand with the definitive source of
      academic journals used in research across the globe.\n",
      "seller": {
        "accountId": "192837475"
      },
      "googlePlusUrl": "https://plus.google.com/+MarsAcademy",
      "samplePageUrl": "https://marsacademy.mf",
      "topHeadlines": ["Largest repository of Mars academic journals", "Trusted
      source for academics around the globe"],
      "logoUrl": "//www.gstatic.com/adx/customerlogos/2521607341/1/1078322542936.jpg",
      "publisherProfileId": "PP55555"
    }
  ]
}

Create proposal

You can use the proposals.create method to initiate negotiation with a publisher. Only publishers can initiate proposals containing more than one deal at this time. In addition, a proposal must have at least one deal.

Note: Not all deal types can be initiated by a buyer. For instance, Private Auction Deals can only be initiated by the publisher.

You can only create proposals for Programmatic Guaranteed Deals with whitelisted sellers. If the seller is not whitelisted, you will receive an error response. To avoid errors, all users of this API (buyers and sellers) need to be whitelisted.

The following request creates a proposal:

View the request

POST https://adexchangebuyer.googleapis.com/v2beta1/accounts/12345678/proposals
{
  "buyer": {
    "accountId": "12345678"
  },
  "deals": [{
    "syndicationProduct": "GAMES",
    "displayName": "Test Deal",
    "dealTerms": {
      "description": "Test deal.",
      "estimatedGrossSpend": {
        "pricingType": "COST_PER_MILLE",
        "amount": {
          "units": "0",
          "nanos": "1",
          "currencyCode": "USD"
        }
      },
      "sellerTimeZone": "America/New_York",
      "estimatedImpressionsPerDay": "1",
      "guaranteedFixedPriceTerms": {
        "guaranteedImpressions": "1",
        "fixedPrices": [{
          "buyer": {
            "accountId": "53728410"
          },
          "price": {
            "pricingType": "COST_PER_MILLE",
            "amount": {
              "units": "0",
              "nanos": "1",
              "currencyCode": "USD"
            }
          }
        }],
        "minimumDailyLooks": "1",
        "guaranteedLooks": "1"
      },
      "brandingType": "BRANDED"
    }
  }],
  "displayName": "Test Proposal",
  "seller": {
    "accountId": "987654321"
  }
}

The server responds with a 200 OK HTTP status code and the created proposal.

View the response

{
  "updateTime": "1985-10-26T01:21:00.000Z",
  "displayName": "Test Proposal",
  "proposalRevision": "1",
  "billedBuyer": {
    "accountId": "12345678"
  },
  "originatorRole": "BUYER",
  "seller": {
    "accountId": "987654321"
  },
  "sellerContacts": [{
    "email": "[e-mail]"
  }],
  "proposalId": "MP11111111",
  "buyer": {
    "accountId": "12345678"
  },
  "deals": [{
    "createTime": "1985-10-26T01:21:00.000Z",
    "creativePreApprovalPolicy": "SELLER_PRE_APPROVAL_NOT_REQUIRED",
    "creativeSafeFrameCompatibility": "COMPATIBLE",
    "dealId": "MP55555555",
    "dealServingMetadata": {
      "dealPauseStatus": {}
    },
    "dealTerms": {
      "brandingType": "BRANDED",
      "description": "Test deal.",
      "estimatedGrossSpend": {
        "amount": {
          "currencyCode": "USD",
          "nanos": 1
        },
        "pricingType": "COST_PER_MILLE"
      },
      "estimatedImpressionsPerDay": "1",
      "guaranteedFixedPriceTerms": {
        "fixedPrices": [{
          "buyer": {
            "accountId": "12345678"
          },
          "price": {
            "amount": {
              "currencyCode": "USD",
              "nanos": 1
            },
            "pricingType": "COST_PER_MILLE"
          }
        }],
        "guaranteedImpressions": "1",
        "guaranteedLooks": "1",
        "minimumDailyLooks": "1"
      },
      "sellerTimeZone": "America/New_York"
    },
    "displayName": "Test Deal",
    "externalDealId": "666666666666666",
    "programmaticCreativeSource": "ADVERTISER",
    "proposalId": "MP11111111",
    "syndicationProduct": "GAMES",
    "updateTime": "1985-10-26T01:21:00.000Z"
  }],
  "proposalState": "PROPOSED",
  "lastUpdaterOrCommentorRole": "BUYER"
}

Revise proposal

After creation, the proposal's proposalRevision will be incremented for every subsequent update, and is required for most API calls. If an API call specifies a proposalRevision that is not equal to the current value, the request will return an error response.

List proposals

You can use the proposals.list method to find proposals undergoing negotiation or those that have completed negotiation.

During renegotiation, only the version of the proposal being renegotiated will be displayed in the proposals.list response. The proposal will continue serving under the former terms while renegotiation takes place, and you can view these with the finalizedProposals resource.

Note: Using PQL to filter results is deprecated. We recommend that you use list filtering, which you can read about in the List Filtering guide.

Use the proposals.list method with a filter set to proposalId = MP11111111 to retrieve the proposal created in the previous example. Note that this request should also specify a filterSyntax of LIST_FILTER; if not specified, the request will fail because the default syntax is PQL at this time.

View the request

GET https://adexchangebuyer.googleapis.com/v2beta1/accounts/12345678/proposals?filter=proposalId+%3D+MP11111111&filterSyntax=LIST_FILTER

The server responds with a 200 OK HTTP status code and proposals matching the filter.

View the response

{
  "proposals": [{
    "updateTime": "1985-10-26T01:21:00.000Z",
    "displayName": "Test Proposal",
    "proposalRevision": "1",
    "billedBuyer": {
      "accountId": "12345678"
    },
    "originatorRole": "BUYER",
    "seller": {
      "accountId": "987654321"
    },
    "sellerContacts": [{
      "email": "[e-mail]"
    }],
    "proposalId": "MP11111111",
    "buyer": {
      "accountId": "12345678"
    },
    "deals": [{
      "createTime": "1985-10-26T01:21:00.000Z",
      "creativePreApprovalPolicy": "SELLER_PRE_APPROVAL_NOT_REQUIRED",
      "creativeSafeFrameCompatibility": "COMPATIBLE",
      "dealId": "MP55555555",
      "dealServingMetadata": {
        "dealPauseStatus": {}
      },
      "dealTerms": {
        "brandingType": "BRANDED",
        "description": "Test deal.",
        "estimatedGrossSpend": {
          "amount": {
            "currencyCode": "USD",
            "nanos": 1
          },
          "pricingType": "COST_PER_MILLE"
        },
        "estimatedImpressionsPerDay": "1",
        "guaranteedFixedPriceTerms": {
          "fixedPrices": [{
            "buyer": {
              "accountId": "12345678"
            },
            "price": {
              "amount": {
                "currencyCode": "USD",
                "nanos": 1
              },
              "pricingType": "COST_PER_MILLE"
            }
          }],
          "guaranteedImpressions": "1",
          "guaranteedLooks": "1",
          "minimumDailyLooks": "1"
        },
        "sellerTimeZone": "America/New_York"
      },
      "displayName": "Test Deal",
      "externalDealId": "666666666666666",
      "programmaticCreativeSource": "ADVERTISER",
      "proposalId": "MP11111111",
      "syndicationProduct": "GAMES",
      "updateTime": "1985-10-26T01:21:00.000Z"
    }],
    "proposalState": "PROPOSED",
    "lastUpdaterOrCommentorRole": "BUYER"
  }]
}

Update proposal

Use the proposals.update method to update a proposal under negotiation or begin renegotiation of a finalized proposal. When updating a proposal, we recommend that you start with a copy and make adjustments as needed, as the contents you provide in the request body—or lack thereof—will replace the specified proposal if the operation succeeds.

Note: This only applies to Preferred Deals and Programmatic Guaranteed Deals. Private Auction Deals can not be updated by the buyer.

The following request updates fixedPrices, guaranteedLooks, and guaranteedImpressions.

View the request

PUT https://adexchangebuyer.googleapis.com/v2beta1/accounts/12345678/proposals/MP11111111
{
  "deals": [{
    "dealTerms": {
      "brandingType": "BRANDED",
      "description": "Test deal.",
      "estimatedGrossSpend": {
        "amount": {
          "currencyCode": "USD",
          "nanos": 1
        },
        "pricingType": "COST_PER_MILLE"
      },
      "estimatedImpressionsPerDay": "1",
      "guaranteedFixedPriceTerms": {
        "fixedPrices": [{
          "buyer": {
            "accountId": "12345678"
          },
          "price": {
            "amount": {
              "currencyCode": "USD",
              "nanos": 100
            },
            "pricingType": "COST_PER_MILLE"
          }
        }],
        "guaranteedImpressions": "50",
        "guaranteedLooks": "10",
      },
      "sellerTimeZone": "America/New_York"
    },
    "displayName": "Test Deal",
    "externalDealId": "666666666666666",
    "programmaticCreativeSource": "ADVERTISER",
    "proposalId": "MP11111111",
    "syndicationProduct": "GAMES",
  }],
  "displayName": "Test Proposal",
  "proposalRevision": "1",
  "billedBuyer": {
    "accountId": "12345678"
  },
  "originatorRole": "BUYER",
  "seller": {
    "accountId": "987654321"
  },
  "sellerContacts": [{
    "email": "[e-mail]"
  }],
  "proposalId": "MP11111111",
  "buyer": {
    "accountId": "12345678"
  },
  "proposalState": "PROPOSED",
  "lastUpdaterOrCommentorRole": "BUYER"
}

The server responds with a 200 OK HTTP status code and the updated proposal.

View the response

{
  "deals": [{
    "dealTerms": {
      "brandingType": "BRANDED",
      "description": "Test deal.",
      "estimatedGrossSpend": {
        "amount": {
          "currencyCode": "USD",
          "nanos": 1
        },
        "pricingType": "COST_PER_MILLE"
      },
      "estimatedImpressionsPerDay": "1",
      "guaranteedFixedPriceTerms": {
        "fixedPrices": [{
          "buyer": {
            "accountId": "12345678"
          },
          "price": {
            "amount": {
              "currencyCode": "USD",
              "nanos": 100
            },
            "pricingType": "COST_PER_MILLE"
          }
        }],
        "guaranteedImpressions": "50",
        "guaranteedLooks": "10",
      },
      "sellerTimeZone": "America/New_York"
    },
    "displayName": "Test Deal",
    "externalDealId": "666666666666666",
    "programmaticCreativeSource": "ADVERTISER",
    "proposalId": "MP11111111",
    "syndicationProduct": "GAMES",
  }],
  "updateTime": "1985-10-26T01:22:00.000Z",
  "displayName": "Test Proposal",
  "proposalRevision": "2",
  "billedBuyer": {
    "accountId": "12345678"
  },
  "originatorRole": "BUYER",
  "seller": {
    "accountId": "987654321"
  },
  "sellerContacts": [{
    "email": "[e-mail]"
  }],
  "proposalId": "MP11111111",
  "buyer": {
    "accountId": "12345678"
  },
  "proposalState": "PROPOSED",
  "lastUpdaterOrCommentorRole": "BUYER"
}

Add note to proposal

Buyers and publishers can add notes to a proposal to provide context for a change and communicate with the other party. To add notes for a particular proposal, you can use the proposals.addNote method. An individual note cannot exceed 1024 unicode characters, and all notes added will be saved to the proposal's notes field. These will be visible to both the buyer and publisher.

Note: Only Preferred Deals and Programmatic Guaranteed Deals can have notes. Notes cannot be applied to Private Auction Deals.

You must use proposals.addNote to add a note.

The following request adds a note to the proposal:

View the request

POST https://adexchangebuyer.googleapis.com/v2beta1/accounts/12345678/proposals/MP11111111:addNote
{
  "note": {
    "note": "This is a test."
  }
}

The server responds with a 200 OK HTTP status code and the Note appended to the proposal.

View the response

{
  "note": "This is a test.",
  "creatorRole": "BUYER",
  "noteId": "MP99999999",
  "createTime": "1985-10-26T01:23:00.000Z"
}

Accept proposal

Use the proposals.accept method to indicate that you accept the terms of a proposal at the current revision. This will update the proposalState to eitherBUYER_ACCEPTED or FINALIZED depending on whether the publisher accepted the proposal previously. The proposal will only become FINALIZED if both parties accept the same proposalRevision.

Note: You must use proposals.accept to accept the terms of a proposal. Be sure to include the current revision number as shown in the request below.

The following request accepts the proposal at the second revision.

View the request

POST https://adexchangebuyer.googleapis.com/v2beta1/accounts/12345678/proposals/MP11111111:accept
{
  "proposalRevision": 2
}

The server responds with a 200 OK HTTP status code and the accepted proposal.

View the response

{
  "sellerContacts": [{
    "email": "[e-mail]"
  }],
  "updateTime": "1985-10-26T01:23:00.000Z",
  "displayName": "Test Proposal",
  "proposalRevision": "3",
  "billedBuyer": {
    "accountId": "12345678"
  },
  "originatorRole": "BUYER",
  "seller": {
    "accountId": "987654321"
  },
  "deals": [{
    "dealTerms": {
      "brandingType": "BRANDED",
      "description": "Test deal.",
      "estimatedGrossSpend": {
        "amount": {
          "currencyCode": "USD",
          "nanos": 1
        },
        "pricingType": "COST_PER_MILLE"
      },
      "estimatedImpressionsPerDay": "1",
      "guaranteedFixedPriceTerms": {
        "fixedPrices": [{
          "buyer": {
            "accountId": "12345678"
          },
          "price": {
            "amount": {
              "currencyCode": "USD",
              "nanos": 100
            },
            "pricingType": "COST_PER_MILLE"
          }
        }],
        "guaranteedImpressions": "50",
        "guaranteedLooks": "10",
      },
      "sellerTimeZone": "America/New_York"
    },
    "displayName": "Test Deal",
    "externalDealId": "666666666666666",
    "programmaticCreativeSource": "ADVERTISER",
    "proposalId": "MP11111111",
    "syndicationProduct": "GAMES",
  }],
  "proposalId": "MP11111111",
  "buyer": {
    "accountId": "12345678"
  },
  "proposalState": "BUYER_ACCEPTED",
  "lastUpdaterOrCommentorRole": "BUYER"
}

Note: In the response above, the proposalState is BUYER_ACCEPTED. The publisher will still need to accept the proposal in order for it to be FINALIZED.

Cancel negotiation

You can cancel the negotiation with the proposals.cancelNegotiation method. If the proposal was not previously finalized, this will set the proposalState to CANCELED, a terminal state where no further updates can be made. Otherwise, the proposal will revert to the last finalized state with the proposalRevision incremented once and the lastUpdaterOrCommentRole set to BUYER.

Note: This only applies to Preferred Deals and Programmatic Guaranteed Deals. Private Auction Deals can not be cancelled by the buyer.

You must use proposals.cancelNegotiation to cancel negotiation of a proposal.

The following request cancels negotiation of a proposal.

View the request

POST https://adexchangebuyer.googleapis.com/v2beta1/accounts/12345678/proposals/MP11111111:cancelNegotiation

The server responds with a 200 OK HTTP status code and the canceled proposal.

View the response

{
  "updateTime": "1985-10-26T01:22:00.000Z",
  "displayName": "Test Proposal",
  "proposalRevision": "2",
  "deals": [{
    "dealTerms": {
      "brandingType": "BRANDED",
      "description": "Test deal.",
      "estimatedGrossSpend": {
        "amount": {
          "currencyCode": "USD",
          "nanos": 1
        },
        "pricingType": "COST_PER_MILLE"
      },
      "estimatedImpressionsPerDay": "1",
      "guaranteedFixedPriceTerms": {
        "fixedPrices": [{
          "buyer": {
            "accountId": "12345678"
          },
          "price": {
            "amount": {
              "currencyCode": "USD",
              "nanos": 100
            },
            "pricingType": "COST_PER_MILLE"
          }
        }],
        "guaranteedImpressions": "50",
        "guaranteedLooks": "10",
      },
      "sellerTimeZone": "America/New_York"
    },
    "displayName": "Test Deal",
    "externalDealId": "666666666666666",
    "programmaticCreativeSource": "ADVERTISER",
    "proposalId": "MP11111111",
    "syndicationProduct": "GAMES",
  }],

  "billedBuyer": {
    "accountId": "12345678"
  },
  "originatorRole": "BUYER",
  "seller": {
    "accountId": "987654321"
  },
  "sellerContacts": [{
    "email": "[e-mail]"
  }],
  "proposalId": "MP11111111",
  "buyer": {
    "accountId": "12345678"
  },
  "proposalState": "CANCELED",
  "notes": [{
    "note": "This is a test.",
    "creatorRole": "BUYER",
    "noteId": "MP99999999",
    "createTime": "1985-10-26T01:23:00.000Z"
  }],
  "lastUpdaterOrCommentorRole": "BUYER"
}

Complete proposal setup

You can indicate to the publisher that you have completed setup for a particular proposal by specifying it with the proposals.completeSetup method after the proposal is finalized. Contact your TAM to find out the process you need to have in place before making this call.

Note: This only applies to Preferred Deals and Programmatic Guaranteed Deals. The buyer cannot complete a proposal setup in Private Auction Deals.

You must use proposals.completeSetup to indicate completion of setup to the publisher. It should be called after the deal's proposalState is FINALIZED.

The following request completes setup for the specified proposal:

View the request

POST https://adexchangebuyer.googleapis.com/v2beta1/accounts/12345678/proposals/MP33333333:completeSetup

The server responds with a 200 OK HTTP status code and the proposal which has completed setup.

View the response

{
  "sellerContacts": [{
    "email": "[e-mail]"
  }],
  "updateTime": "2018-01-01T00:00:00.000Z",
  "displayName": "Test Proposal",
  "proposalRevision": "388",
  "billedBuyer": {
    "accountId": "12345678"
  },
  "originatorRole": "BUYER",
  "seller": {
    "accountId": "192837475"
  },
  "deals": [{
    "deliveryControl": {
      "creativeBlockingLevel": "PUBLISHER_BLOCKING_RULES"
    },
    "programmaticCreativeSource": "ADVERTISER",
    "updateTime": "2018-01-01T00:00:00.000Z",
    "displayName": "Test Deal",
    "syndicationProduct": "CONTENT",
    "targetingCriterion": [{
      "inclusions": [{
        "creativeSizeValue": {
          "creativeSizeType": "REGULAR",
          "size": {
            "width": 950,
            "height": 200
          }
        }
      }, {
        "creativeSizeValue": {
          "creativeSizeType": "REGULAR",
          "size": {
            "width": 720,
            "height": 100
          }
        }
      }, {
        "creativeSizeValue": {
          "creativeSizeType": "REGULAR",
          "size": {
            "width": 420,
            "height": 600
          }
        }
      }],
      "key": "GOOG_CREATIVE_SIZE"
    }],
    "sellerContacts": [{
      "email": "[e-mail]"
    }],
    "webPropertyCode": "ca-pub-4444444444444444",
    "proposalId": "MP33333333",
    "dealServingMetadata": {
      "dealPauseStatus": {}
    },
    "creativeSafeFrameCompatibility": "COMPATIBLE",
    "creativePreApprovalPolicy": "SELLER_PRE_APPROVAL_NOT_REQUIRED",
    "externalDealId": "666666666666666",
    "dealId": "MP55555555",
    "createTime": "2017-12-24T23:00:00.000Z",
    "dealTerms": {
      "description": "Test deal.",
      "estimatedGrossSpend": {
        "pricingType": "COST_PER_MILLE",
        "amount": {
          "nanos": 10,
          "currencyCode": "USD"
        }
      },
      "sellerTimeZone": "America/New_York",
      "estimatedImpressionsPerDay": "1",
      "guaranteedFixedPriceTerms": {
        "guaranteedImpressions": "1",
        "fixedPrices": [{
          "buyer": {
            "accountId": "12345678"
          },
          "price": {
            "pricingType": "COST_PER_MILLE",
            "amount": {
              "nanos": 1,
              "currencyCode": "USD"
            }
          }
        }],
        "minimumDailyLooks": "1",
        "guaranteedLooks": "1"
      },
      "brandingType": "BRANDED"
    }
  }],
  "proposalId": "MP33333333",
  "isSetupComplete": True,
  "buyer": {
    "accountId": "12345678"
  },
  "proposalState": "FINALIZED"
}

Manage serving proposals

List proposals

Use the finalizedProposals.list method to view proposals that have been finalized, including those that are paused or ended. If a proposal enters renegotiation, the version of that proposal returned in the response will reflect the previous terms of the proposal that are still serving.

Note: Using PQL to filter results is deprecated. We recommend that you use list filtering, which you can read about in the List Filtering guide.

To view proposals that are undergoing renegotiation, use the proposals.list method.

The following request retrieves finalized proposals with a list filter specifying a specific proposalId:

View the request

GET https://adexchangebuyer.googleapis.com/v2beta1/accounts/12345678/finalizedProposals?filter=proposalId+%3D+MP33333333&filterSyntax=LIST_FILTER

The server responds with a `200 OK` HTTP status code and the proposals specified by the filter; in this case, only a single proposal is returned.

View the response

{
  "nextPageToken": "DGUQkOChk4aO4BJru0VnkkbO6FK",
  "proposals": [
    {
      "sellerContacts": [{
        "email": "[e-mail]"
      }],
      "updateTime": "2018-01-01T00:00:00.000Z",
      "displayName": "Test Proposal",
      "proposalRevision": "0",
      "billedBuyer": {
        "accountId": "12345678"
      },
      "originatorRole": "BUYER",
      "seller": {
        "accountId": "192837475"
      },
      "deals": [{
        "deliveryControl": {
          "creativeBlockingLevel": "PUBLISHER_BLOCKING_RULES"
        },
        "programmaticCreativeSource": "ADVERTISER",
        "updateTime": "2018-01-01T00:00:00.000Z",
        "displayName": "Test Deal",
        "syndicationProduct": "CONTENT",
        "targetingCriterion": [{
          "inclusions": [{
            "creativeSizeValue": {
              "creativeSizeType": "REGULAR",
              "size": {
                "width": 950,
                "height": 200
              }
            }
          }, {
            "creativeSizeValue": {
              "creativeSizeType": "REGULAR",
              "size": {
                "width": 720,
                "height": 100
              }
            }
          }, {
            "creativeSizeValue": {
              "creativeSizeType": "REGULAR",
              "size": {
                "width": 420,
                "height": 600
              }
            }
          }],
          "key": "GOOG_CREATIVE_SIZE"
        }],
        "sellerContacts": [{
          "email": "[e-mail]"
        }],
        "webPropertyCode": "ca-pub-4444444444444444",
        "proposalId": "MP33333333",
        "dealServingMetadata": {
          "dealPauseStatus": {}
        },
        "creativeSafeFrameCompatibility": "COMPATIBLE",
        "creativePreApprovalPolicy": "SELLER_PRE_APPROVAL_NOT_REQUIRED",
        "externalDealId": "666666666666666",
        "dealId": "MP55555555",
        "createTime": "2017-12-24T23:00:00.000Z",
        "dealTerms": {
          "description": "Test deal.",
          "estimatedGrossSpend": {
            "pricingType": "COST_PER_MILLE",
            "amount": {
              "nanos": 10,
              "currencyCode": "USD"
            }
          },
          "sellerTimeZone": "America/New_York",
          "estimatedImpressionsPerDay": "1",
          "guaranteedFixedPriceTerms": {
            "guaranteedImpressions": "1",
            "fixedPrices": [{
              "buyer": {
                "accountId": "12345678"
              },
              "price": {
                "pricingType": "COST_PER_MILLE",
                "amount": {
                  "nanos": 1,
                  "currencyCode": "USD"
                }
              }
            }],
            "minimumDailyLooks": "1",
            "guaranteedLooks": "1"
          },
          "brandingType": "BRANDED"
        }
      }],
      "proposalId": "MP33333333",
      "isSetupComplete": True,
      "buyer": {
        "accountId": "12345678"
      },
      "proposalState": "FINALIZED"
    }
  ]
}

Note: Finalized proposals will always have a proposalRevision set to 0.

Pause

Use the proposals.pause method to indefinitely stop serving a particular proposal.

This only applies to Preferred Deals and Programmatic Guaranteed Deals.

Warning: If a seller pauses a proposal, only they can unpause it. Calling resume as a buyer after the seller pauses the proposal doesn't change the status of the proposal. In Private Auction Deals, the buyer cannot resume serving a proposal even if the buyer paused it.

The following request pauses a finalized proposal, specifying the reason for pausing.

View the request

POST https://adexchangebuyer.googleapis.com/v2beta1/accounts/12345678/proposals/MP33333333:pause
{
  "reason": "This is a test."
}

The server responds with a 200 OK HTTP status code and the paused proposal.

View the response

{
  "sellerContacts": [{
    "email": "[e-mail]"
  }],
  "updateTime": "2018-01-02T00:00:00.000Z",
  "displayName": "Test Proposal",
  "proposalRevision": "389",
  "billedBuyer": {
    "accountId": "12345678"
  },
  "originatorRole": "BUYER",
  "seller": {
    "accountId": "192837475"
  },
  "deals": [{
    "deliveryControl": {
      "creativeBlockingLevel": "PUBLISHER_BLOCKING_RULES"
    },
    "programmaticCreativeSource": "ADVERTISER",
    "updateTime": "2018-01-01T00:00:00.000Z",
    "displayName": "Test Deal",
    "syndicationProduct": "CONTENT",
    "targetingCriterion": [{
      "inclusions": [{
        "creativeSizeValue": {
          "creativeSizeType": "REGULAR",
          "size": {
            "width": 950,
            "height": 200
          }
        }
      }, {
        "creativeSizeValue": {
          "creativeSizeType": "REGULAR",
          "size": {
            "width": 720,
            "height": 100
          }
        }
      }, {
        "creativeSizeValue": {
          "creativeSizeType": "REGULAR",
          "size": {
            "width": 420,
            "height": 600
          }
        }
      }],
      "key": "GOOG_CREATIVE_SIZE"
    }],
    "sellerContacts": [{
      "email": "[e-mail]"
    }],
    "webPropertyCode": "ca-pub-4444444444444444",
    "proposalId": "MP33333333",
    "dealServingMetadata": {
      "dealPauseStatus": {
        "hasBuyerPaused": True,
        "firstPausedBy": "BUYER",
        "buyerPauseReason": "This is a test."
      }
    },
    "creativeSafeFrameCompatibility": "COMPATIBLE",
    "creativePreApprovalPolicy": "SELLER_PRE_APPROVAL_NOT_REQUIRED",
    "externalDealId": "666666666666666",
    "dealId": "MP55555555",
    "createTime": "2017-12-24T23:00:00.000Z",
    "dealTerms": {
      "description": "Test deal.",
      "estimatedGrossSpend": {
        "pricingType": "COST_PER_MILLE",
        "amount": {
          "nanos": 10,
          "currencyCode": "USD"
        }
      },
      "sellerTimeZone": "America/New_York",
      "estimatedImpressionsPerDay": "1",
      "guaranteedFixedPriceTerms": {
        "guaranteedImpressions": "1",
        "fixedPrices": [{
          "buyer": {
            "accountId": "12345678"
          },
          "price": {
            "pricingType": "COST_PER_MILLE",
            "amount": {
              "nanos": 1,
              "currencyCode": "USD"
            }
          }
        }],
        "minimumDailyLooks": "1",
        "guaranteedLooks": "1"
      },
      "brandingType": "BRANDED"
    }
  }],
  "proposalId": "MP33333333",
  "isSetupComplete": True,
  "buyer": {
    "accountId": "12345678"
  },
  "proposalState": "FINALIZED"
}

Resume

Use the proposals.resume method to resume serving of a particular proposal after it's paused.

Caution: The following restrictions apply to proposals.resume.

• This method only applies to Preferred Deals and Programmatic Guaranteed Deals.
• If the seller pauses a proposal, only the seller can unpause it.
• In Private Auction Deals, the buyer cannot resume a proposal no matter who paused it.

The following request resumes a finalized proposal:

View the request

POST https://adexchangebuyer.googleapis.com/v2beta1/accounts/12345678/proposals/MP33333333:resume.

The server responds with a 200 OK HTTP status code and the resumed proposal.

View the response

{
  "sellerContacts": [{
    "email": "[e-mail]"
  }],
  "updateTime": "2018-01-03T00:00:00.000Z",
  "displayName": "Test Proposal",
  "proposalRevision": "390",
  "billedBuyer": {
    "accountId": "12345678"
  },
  "originatorRole": "BUYER",
  "seller": {
    "accountId": "192837475"
  },
  "deals": [{
    "deliveryControl": {
      "creativeBlockingLevel": "PUBLISHER_BLOCKING_RULES"
    },
    "programmaticCreativeSource": "ADVERTISER",
    "updateTime": "2018-01-01T00:00:00.000Z",
    "displayName": "Test Deal",
    "syndicationProduct": "CONTENT",
    "targetingCriterion": [{
      "inclusions": [{
        "creativeSizeValue": {
          "creativeSizeType": "REGULAR",
          "size": {
            "width": 950,
            "height": 200
          }
        }
      }, {
        "creativeSizeValue": {
          "creativeSizeType": "REGULAR",
          "size": {
            "width": 720,
            "height": 100
          }
        }
      }, {
        "creativeSizeValue": {
          "creativeSizeType": "REGULAR",
          "size": {
            "width": 420,
            "height": 600
          }
        }
      }],
      "key": "GOOG_CREATIVE_SIZE"
    }],
    "sellerContacts": [{
      "email": "[e-mail]"
    }],
    "webPropertyCode": "ca-pub-4444444444444444",
    "proposalId": "MP33333333",
    "dealServingMetadata": {
      "dealPauseStatus": {}
    },
    "creativeSafeFrameCompatibility": "COMPATIBLE",
    "creativePreApprovalPolicy": "SELLER_PRE_APPROVAL_NOT_REQUIRED",
    "externalDealId": "666666666666666",
    "dealId": "MP55555555",
    "createTime": "2017-12-24T23:00:00.000Z",
    "dealTerms": {
      "description": "Test deal.",
      "estimatedGrossSpend": {
        "pricingType": "COST_PER_MILLE",
        "amount": {
          "nanos": 10,
          "currencyCode": "USD"
        }
      },
      "sellerTimeZone": "America/New_York",
      "estimatedImpressionsPerDay": "1",
      "guaranteedFixedPriceTerms": {
        "guaranteedImpressions": "1",
        "fixedPrices": [{
          "buyer": {
            "accountId": "12345678"
          },
          "price": {
            "pricingType": "COST_PER_MILLE",
            "amount": {
              "nanos": 1,
              "currencyCode": "USD"
            }
          }
        }],
        "minimumDailyLooks": "1",
        "guaranteedLooks": "1"
      },
      "brandingType": "BRANDED"
    }
  }],
  "proposalId": "MP33333333",
  "isSetupComplete": True,
  "buyer": {
    "accountId": "12345678"
  },
  "proposalState": "FINALIZED"
}