This guide explains "what a proposal is" and walks you through the creation of a Proposal object via the API. It also describes what you can do once you've created your proposal.


A programmatic proposal is similar to an order in Google Ad Manager. Programmatic proposals contain broad information about a proposed transaction between you and a buyer. A proposal, together with its line items, represents an offer of inventory to a buyer.

For more information see the Help Center.

Creating a proposal via the API

To create a Proposal object, only the name and programmatic buyer are required. The programmatic buyer ID can be obtained through the UI or the Programmatic_Buyer PQL table.


Proposal proposal = new Proposal();

// Setting required Marketplace information.
ProposalMarketplaceInfo proposalMarketplaceInfo = new ProposalMarketplaceInfo();

// Set common required fields for a programmatic proposal.
proposal.setName("Proposal #" + new Random().nextInt(Integer.MAX_VALUE));
View on GitHub


proposal = {
    # Setting required Marketplace information.
    'isProgrammatic': 'true',
    'marketplaceInfo': {
        'buyerAccountId': programmatic_buyer_id,
    # Set common required fields for proposals.
    'name': 'Proposal #%s' % uuid.uuid4(),
    # ...
View on GitHub


$proposal = new Proposal();
$proposal->setName('Proposal #' . uniqid());

// Set the required Marketplace information.
$proposalMarketplaceInfo = new ProposalMarketplaceInfo();
View on GitHub


// Create a proposal with the minimum required fields.
Proposal proposal = new Proposal()
    name = "Programmatic proposal #" + new Random().Next(int.MaxValue),
    isProgrammatic = true,
    // Set required Marketplace information
    marketplaceInfo = new ProposalMarketplaceInfo()
        buyerAccountId = programmaticBuyerId
View on GitHub

Before sending to the buyer for negotiation, additional fields will need to be set. The proposal must have an advertiser, salesperson, trafficker, and seller contacts.


// Set fields that are required before sending the proposal to the buyer.
proposal.setSellerContactIds(new long[] { primarySalespersonId });
SalespersonSplit primarySalesperson = new SalespersonSplit();
ProposalCompanyAssociation advertiser = new ProposalCompanyAssociation();
View on GitHub


# ...
# Set fields that are required before sending the proposal to the buyer.
'primaryTraffickerId': primary_trafficker_id,
'sellerContactIds': [primary_salesperson_id],
'primarySalesperson': {
    'userId': primary_salesperson_id,
    'split': '100000'
'advertiser': {
    'type': 'ADVERTISER',
    'companyId': advertiser_id
# ...
View on GitHub


// Create salesperson splits for the primary salesperson.
$primarySalesperson = new SalespersonSplit();

// Set the primary trafficker on the proposal for when it becomes an
// order.

$advertiser = new ProposalCompanyAssociation();
View on GitHub


// Set fields that are required before sending the proposal to the buyer.
proposal.primaryTraffickerId = primaryTraffickerId;
proposal.sellerContactIds = new long[] { primarySalespersonId };
proposal.primarySalesperson = new SalespersonSplit()
    userId = primarySalespersonId,
    split = 100000
proposal.advertiser = new ProposalCompanyAssociation()
    type = ProposalCompanyAssociationType.ADVERTISER,
    companyId = advertiserId
View on GitHub

Since proposals are generally comprised of ProposalLineItem objects, the next step would be to add proposal line items beneath your newly created proposal.

States of a programmatic proposal

The following figure depicts a programmatic proposal at various points during the negotiation process from an API standpoint. Each state is represented by various combinations of the following fields:

For more infotmation see the Ad Manager Help Center.

The states a programmatic proposal can be in during its
           interaction with Marketplace.
Figure 1: States of a programmatic proposal

Negotiation walkthrough

Here, we'll walk you through using the API to complete a negotiation for a programmatic proposal with a buyer. We'll reference the states in the diagram above.

Preparing for buyer review or acceptance

First, you need to draft a programmatic proposal with proposal line items that you want to send to a buyer. This is state C in the figure above.

Requesting buyer reivew or acceptance

Once you're ready to have the buyer review the programmatic proposal, you can RequestBuyerReview or RequestBuyerAcceptance by using the ProposalService.performProposalAction method. This will bring you into the negotiation phase.


In this phase, a number of things may happen.

  • The buyer may accept your programmatic proposal without changes.
  • The buyer may propose changes. In this case, the proposal will be sent back to a draft state (state B in Figure 1). You will then need to open the proposal for edit, make the proposed changes, and send it back for the buyer's review.
  • You may also decide to make changes even before the buyer replies. You can do this by opening the proposal for edit from state D in Figure 1.

This negotiation continues until you reach an agreement with the buyer. Comments between you and the buyer can be retrieved using getMarketplaceCommentsByStatement. You can send a comment to the buyer while in state A. To do this, you will need to update the marketplaceComment field on the proposal using updateProposals. The comment will then be sent when you request buyer acceptance.


When both you and the buyer have both accepted the programmatic proposal, it goes into a finalized state (state F in Figure 1). Ad Manager then automatically creates line items from this programmatic proposal.

In most cases you are now done with the programmatic proposal. But there are two actions you can perform from this state:

  • You may re-open the programmatic proposal for renegotiation by editing serving-related fields on the proposal. You can do this by opening the proposal for edit (state E to A in Figure 1), making changes, and then requesting buyer acceptance.
  • You may make non-serving related edits, such as updating the proposal's name, and reflecting these changes in the Ad Manager order and line items created from this deal. You can do this by editing the from state E in Figure 1 and then performing the UpdateOrderWithSellerData action.

Send feedback about...

Ad Manager API
Ad Manager API
Need help? Visit our support page.