Marketplace resources

Stay organized with collections Save and categorize content based on your preferences.

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:

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

Find publishers

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

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.

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

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.

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:

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

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.

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.

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

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.

The following request updates fixedPrices, guaranteedLooks, and guaranteedImpressions.

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

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.

You must use proposals.addNote to add a note.

The following request adds a note to the proposal:

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

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.

The following request accepts the proposal at the second revision.

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

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.

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

The following request cancels negotiation of a proposal.

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

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.

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:

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

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.

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:

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.


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

This only applies to Preferred Deals and Programmatic Guaranteed Deals.

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

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


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

  • 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:

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