Migrate to Marketplace API

Enable the API

Similar to other Authorized Buyers' APIs, you need to enable the Marketplace API before you can use it. You can enable the Marketplace API with the following steps:

  1. Go to the Google API Console Enabled APIs page. Select the project you use to access other Authorized Buyers APIs, such as Ad Exchange Buyer II or Real-time Bidding API.
  2. Click the + ENABLE APIS AND SERVICES link.
  3. In the search box, type "Authorized Buyers Marketplace API", and press Enter.
  4. In the search results, select Authorized Buyers Marketplace API.
  5. Click the ENABLE button to enable the Marketplace API.
  6. You should now be able to access the Marketplace API with credentials created under this project.

Update your OAuth 2.0 credentials

Existing OAuth 2.0 workflows with the Ad Exchange Buyer II API scope need to be changed to use the Marketplace API scope:

https://www.googleapis.com/auth/authorized-buyers-marketplace

We recommend using the Service Account OAuth 2.0 flow to access the API. All supported OAuth 2.0 flows must specify the new API scope to request a token from Google that can access Marketplace API.

Mapping Ad Exchange Buyer II API resources to the Marketplace API

Clients

If you use Ad Exchange Buyer II API's accounts.clients resource, you can migrate to Marketplace API's buyers.clients resource.

Resource methods

Ad Exchange Buyer II API Marketplace API
accounts.clients.create buyers.clients.create
accounts.clients.get buyers.clients.get
accounts.clients.list buyers.clients.list

This method now supports list filters.

accounts.clients.update buyers.clients.patch

This method now supports partial updates with the updateMask parameter.

Resource fields

Ad Exchange Buyer II API Marketplace API
Client.clientAccountId Client.name

The clientAccountId is the client resource ID.

Client.role Client.role
Client.status Client.state
Client.clientName Client.displayName
Client.visibleToSeller Client.sellerVisible
Client.entityType

This field has been sunset.

Client.entityId

This field has been sunset.

Client.entityName

This field has been sunset.

Client.partnerClientId Client.partnerClientId

Invitations & Users

Marketplace API combines the functionality of Ad Exchange Buyer II API's accounts.clients.invitations and accounts.clients.users resources into a single buyers.clients.users resource.

Resource methods

Ad Exchange Buyer II API Marketplace API
accounts.clients.invitations.create buyers.clients.users.create
accounts.clients.invitations.get buyers.clients.users.get
accounts.clients.invitations.list buyers.clients.users.list

Only users with their state set to INVITED will be equivalent to those returned by accounts.clients.invitations.list.

accounts.clients.users.get buyers.clients.users.get
accounts.clients.users.list buyers.clients.users.list
accounts.clients.users.update

You can no longer patch client users with the API. We recommend that you use buyers.clients.users.delete to delete the client user and recreate it with the desired changes.

Resource fields

Ad Exchange Buyer II API Marketplace API
ClientUserInvitation.invitationId

This field has been sunset.

ClientUserInvitation.email ClientUser.email
ClientUserInvitation.clientAccountId

This field no longer exists for client users. Instead, view the clientAccountId in the name of the parent client.

ClientUser.userId ClientUser.name

The userId is the user resource ID.

ClientUser.clientAccountId

This field no longer exists for client users. Instead, view the clientAccountId in the name of the parent client.

ClientUser.status ClientUser.state
ClientUser.email ClientUser.email

Products

This resource and its functionality aren't available in Marketplace API.

PublisherProfiles

If you use Ad Exchange Buyer II API's accounts.publisherProfiles resource, you can migrate to Marketplace API's buyers.publisherProfiles resource.

Resource methods

Ad Exchange Buyer II API Marketplace API
accounts.publisherProfiles.get buyers.publisherProfiles.get
accounts.publisherProfiles.list buyers.publisherProfiles.list

This method now supports list filters.

Resource fields

Ad Exchange Buyer II API Marketplace API
PublisherProfile.publisherProfileId PublisherProfile.name

The publisherProfileId is the publisher profile resource ID.

PublisherProfile.seller.accountId PublisherProfile.seller.accountId
PublisherProfile.seller.subAccountId PublisherProfile.seller.subAccountId
PublisherProfile.displayName PublisherProfile.displayName
PublisherProfile.domains PublisherProfile.domains
PublisherProfile.mobileApps PublisherProfile.mobileApps
PublisherProfile.logoUrl PublisherProfile.logoUrl
PublisherProfile.directDealsContact PublisherProfile.directDealsContact
PublisherProfile.programmaticDealsContact PublisherProfile.programmaticDealsContact
PublisherProfile.mediaKitUrl PublisherProfile.mediaKitUrl
PublisherProfile.samplePageUrl PublisherProfile.samplePageUrl
PublisherProfile.rateCardUrl

This field has been sunset.

PublisherProfile.googlePlusUrl

This field has been sunset.

PublisherProfile.overview PublisherProfile.overview
PublisherProfile.buyerPitchStatement PublisherProfile.pitchStatement
PublisherProfile.topHeadlines PublisherProfile.topHeadlines
PublisherProfile.audienceDescription PublisherProfile.audienceDescription
PublisherProfile.isParent PublisherProfile.isParent

Proposals & FinalizedProposals

If you use Ad Exchange Buyer II API's accounts.proposals resource, you can migrate to Marketplace API's buyers.proposals resource. Deals have been separated from proposals into the buyers.proposals.deals sub-resource. Finalized proposals are no longer represented in the API, giving you more granular control of finalized deals with the buyers.finalizedDeals resource.

Resource methods

Ad Exchange Buyer II API Marketplace API
accounts.proposals.accept buyers.proposals.accept
accounts.proposals.addNote buyers.proposals.addNote
accounts.proposals.cancelNegotiation buyers.proposals.cancelNegotiation
accounts.proposals.completeSetup buyers.finalizedDeals.setReadyToServe
accounts.proposals.create buyers.proposals.sendRfp
accounts.proposals.get buyers.proposals.get

Note that the proposal will no longer contain information about deals.

accounts.proposals.list buyers.proposals.list

Note that the returned proposals will no longer contain information about deals. If you use list filtering, note that Marketplace API only supports list filter syntax.

accounts.proposals.pause buyers.finalizedDeals.pause
accounts.proposals.resume buyers.finalizedDeals.resume
accounts.proposals.update buyers.proposals.patch

This method now supports partial updates with the updateMask parameter.

accounts.finalizedProposals.list

Use buyers.finalizedDeals.list to see finalized deals for a given buyer account. It is now possible to retrieve finalized deals at the bidder level with bidders.finalizedDeals.list.

accounts.finalizedProposals.pause

Use buyers.finalizedDeals.pause to pause individual finalized deals for a given buyer account.

accounts.finalizedProposals.resume

Use buyers.finalizedDeals.resume to resume individual finalized deals for a given buyer account.

Resource fields

The proposals and finalizedProposals resources share the same Proposal representation and have similar migration steps.

Ad Exchange Buyer II API Marketplace API
Proposal.proposalId Proposal.name

The proposalId is the proposal resource ID.

Proposal.updateTime Proposal.updateTime
Proposal.proposalRevision

Proposal.proposalRevision and Deal.proposalRevision

Proposal.deals.dealId Deal.name

The dealId is the deal resource ID.

Proposal.deals.proposalId Deal.name

The proposalId is the parent proposal resource ID.

Proposal.deals.createTime Deal.createTime
Proposal.deals.updateTime Deal.updateTime
Proposal.deals.createProductId

This field has been sunset.

Proposal.deals.createProductRevision

This field has been sunset.

Proposal.deals.displayName Deal.displayName
Proposal.deals.buyerPrivateData.referenceId

This field has been sunset; it is now only exposed at the proposal level.

Proposal.deals.dealTerms.description Deal.description
Proposal.deals.dealTerms.brandingType

This field has been sunset.

Proposal.deals.dealTerms.estimatedGrossSpend Deal.estimatedGrossSpend
Proposal.deals.dealTerms.estimatedImpressionsPerDay

This field has been sunset.

Proposal.deals.dealTerms.sellerTimeZone Deal.sellerTimeZone
Proposal.deals.dealTerms.guaranteedFixedPriceTerms Deal.programmaticGuaranteedTerms
Proposal.deals.dealTerms.nonGuaranteedFixedPriceTerms Deal.preferredDealTerms
Proposal.deals.dealTerms.NonGuaranteedAuctionTerms Deal.privateAuctionTerms
Proposal.deals.webPropertyCode

This field has been sunset.

Proposal.deals.sellerContacts Proposal.sellerContacts
Proposal.deals.availableStartTime Proposal.flightStartTime
Proposal.deals.availableEndTime Proposal.flightEndTime
Proposal.deals.description Proposal.description
Proposal.deals.targetingCriterion Deal.targeting

It is no longer possible to configure targeting using a key to determine the targeting category; however, categories that could be targeted can be found in Deal.targeting. For example, the GOOG_CREATIVE_SIZE key from Ad Exchange Buyer II refers to Marketplace API's Deal.targeting.inventorySizeTargeting.

Proposal.deals.targeting Deal.targeting

Additional targeting criteria categories have been added.

Proposal.deals.creativeRestrictions.creativeFormat Deal.creativeRequirements.creativeFormat
Proposal.deals.creativeRestrictions.skippableAdType Deal.creativeRequirements.skippableAdType
Proposal.deals.creativeRestrictions.creativeSpecifications.creativeSize Deal.targeting.inventorySizeTargeting
Proposal.deals.externalDealId

This field has been sunset.

Proposal.deals.syndicationProduct

This field has been sunset.

Proposal.deals.creativePreApprovalPolicy Deal.creativeRequirements.creativePreApprovalPolicy
Proposal.deals.creativeSafeFrameCompatibility Deal.creativeRequirements.creativeSafeFrameCompatibility
Proposal.deals.dealServingMetadata

Similar information can be found in the FinalizedDeal.dealPausingInfo field.

Proposal.deals.programmaticCreativeSource Deal.creativeRequirements.programmaticCreativeSource
Proposal.deals.deliveryControl Deal.deliveryControl

Additional details about how deals will place have been added.

Proposal.deals.isSetupComplete FinalizedDeal.readyToServe

You can now only signal that a deal is ready to serve if it is finalized. Use the buyers.finalizedDeals.setReadyToServe method to indicate that your finalized Programmatic Guaranteed deal is ready for serving.

Proposal.originatorRole Proposal.originatorRole
Proposal.seller.accountId Proposal.publisherProfile

Use the publisher profile name to identify the seller. You can view publisher profiles with the buyers.publisherProfiles resource.

Proposal.seller.subAccountId Proposal.publisherProfile

Use the publisher profile name to identify the seller. You can view publisher profiles with the buyers.publisherProfiles resource.

Proposal.buyer.accountId

Proposal.buyer or Proposal.client.

The field used will depend on the account type of the negotiating buyer. These are resource names of either a Real-time Bidding API buyers resource, or Marketplace API buyers.clients resource respectively.

Proposal.billedBuyer.accountId Proposal.billedBuyer

This is now a resource name referring to a buyer account as represented in the Real-time Bidding API's buyers resource.

Proposal.displayName Proposal.displayName
Proposal.proposalState Proposal.state
Proposal.isRenegotiating Proposal.isRenegotiating
Proposal.buyerPrivateData Proposal.buyerPrivateData
Proposal.sellerContacts Proposal.sellerContacts
Proposal.buyerContacts Proposal.buyerContacts
Proposal.privateAuctionId

This field has been sunset.

Proposal.isSetupComplete FinalizedDeal.readyToServe

Now accessed more granularly with buyers.finalizedDeals.

Proposal.lastUpdaterOrCommentorRole Proposal.lastUpdaterOrCommentorRole
Proposal.notes.proposalRevision

This field has been sunset.

Proposal.notes.noteId

This field has been sunset.

Proposal.notes.createTime Proposal.notes.createTime
Proposal.notes.creatorRole Proposal.notes.creatorRole
Proposal.notes.note Proposal.notes.note
Proposal.termsAndConditions Proposal.termsAndConditions