Migrate account linking

The management of account relationships has evolved from a single link method in the Content API for Shopping to a more granular and explicit system in the Merchant API. The new API uses dedicated resources like AccountRelationship and AccountService to define the specific services one account provides to another. For more details, see Relationships between accounts.

Key differences

  • Dedicated resources for relationships and services: In Merchant API, the AccountRelationship resource defines the connection between a service provider and a merchant, while the AccountService resource specifies the exact service being provided (for example accountAggregation). This replaces the generic linkType and services fields from the Content API for Shopping.
  • Explicit action methods: Instead of a single link method with an action parameter, Merchant API uses distinct methods for managing services, such as propose, approve, and reject.
  • Dedicated Google Business Profile linking: Linking to a Google Business Profile, previously handled by setting the googleMyBusinessLink field, now has a dedicated method, gbpAccounts.linkGbpAccount.
  • Client account creation as a service: Creating a client account under an advanced account is now treated as proposing an accountAggregation service using the accounts.createAndConfigure method. More information on accounts is available on the Merchant Accounts API page. No handshake is necessary, since the user has access to both advanced account and client account.

Requests

Merchant API provides specific endpoints for managing different types of account links and services:

Merchant API request URLs

  • Propose a new service: POST https://merchantapi.googleapis.com/accounts/v1/ {parent=accounts/*}/services:propose
  • Approve a service: POST https://merchantapi.googleapis.com/accounts/v1/ {name=accounts/*/services/*}:approve
  • Reject a service: POST https://merchantapi.googleapis.com/accounts/v1/ {name=accounts/*/services/*}:reject
  • Link to a Google Business Profile: POST https://merchantapi.googleapis.com/accounts/v1/ {parent=accounts/*}/gbpAccounts:linkGbpAccount
  • Create a client account (account aggregation link): POST https://merchantapi.googleapis.com/accounts/v1/ accounts:createAndConfigure

Request URL comparison

Request description Content API for Shopping Merchant API
Link accounts (for example, third-party platforms) POST .../v2.1/{merchantId}/accounts/{accountId}/link POST .../v1/{parent=accounts/*}/services:propose
Link to Google Business Profile PUT .../v2.1/{merchantId}/accounts/{accountId} (with googleMyBusinessLink field) POST .../v1/{parent=accounts/*}/gbpAccounts:linkGbpAccount
Create a client account POST .../v2.1/{merchantId}/accounts POST .../v1/accounts:createAndConfigure

Methods

Content API for Shopping method Merchant API method Availability & notes
accounts.link accountServices.propose Use this method to initiate a new service with another account.
accounts.link (with action: "approve") accountServices.approve Use this method to approve a pending service proposal.
accounts.link (with action: "remove") accountServices.reject Use this method to reject a pending or established service.
accounts.insert (for client accounts) accounts.createAndConfigure Use this method with an accountAggregation service to create a new client account under an advanced account.
accounts.update (with googleMyBusinessLink) gbpAccounts.linkGbpAccount Use this dedicated method to link a Merchant Center account to a Google Business Profile.
accounts.update (with adsLinks) AccountRelationship resource Linking to Google Ads is managed from the Google Ads UI. The resulting link is represented as an AccountRelationship in Merchant API, which can be viewed but not created directly.

Detailed field changes

Content API for Shopping Merchant API Description
AccountsLinkRequest.action propose, approve, reject methods The single action field is replaced by dedicated API methods for each state change in the service lifecycle.
AccountsLinkRequest.linkType AccountService.service_type The generic linkType string is replaced by a structured service_type oneof field within the AccountService resource, such as productsManagement or accountAggregation
AccountsLinkRequest.services AccountService.service_type The list of string-based services is now represented by the specific service_type chosen within the AccountService resource.
AccountsLinkRequest.linkedAccountId ProposeAccountServiceRequest.provider The ID of the account providing the service is now specified in the provider field of the propose request.
Account.googleMyBusinessLink LinkGbpAccountRequest The object containing GBP link details is replaced by a dedicated request message for the linkGbpAccount method.
Account.adsLinks AccountRelationship Google Ads links are represented as an AccountRelationship resource where the provider is providers/GOOGLE_ADS. This relationship is typically managed from the Google Ads UI.