Manage account relationships

  • Merchant accounts can be linked through various relationships, defining the services one account provides to another.

  • Each relationship includes a service provider, an external account ID, a service recipient, and the service(s) offered.

  • A primary relationship type is "account aggregation," where an aggregator (like an advanced account) provides services to sub-accounts.

  • The service type specifies the access level granted to the service provider, such as admin access in account aggregation.

  • Advanced accounts can manage sub-accounts, enabling third-party platforms to manage merchants under their hierarchy.

You can use the Accounts API to manage the relationships between your Merchant Center account and other service providers. A relationship is a formal connection that enables a provider to offer specific services to your business. A service defines the permissions and capabilities granted to the provider, such as product management or campaign management. For example, linking your Merchant Center account to a Google Ads account allows the Ads account to use your product data for running ad campaigns.

A relationship is composed of the following attributes:

  • The Merchant Center account receiving the service
  • The service provider
  • The service or set of services being provided to the Merchant Center account

Alias

Service providers can associate an alias with accounts they service (this is the equivalent of the seller_id field that was present in the account resource in Content API for Shopping). The alias can be assigned using the optional account_id_alias field within the AccountRelationship resource and serves as a custom identifier. The alias must consist of 1 to 50 characters chosen from ASCII letters, decimal digits, hyphens, underscores, periods, or tildes ([A-Za-z0-9_~.-]{1,50}).

The URL structure for accessing an account using its alias is GET /accounts/v1/accounts/{provider}~{account_id_alias}.

Services

In the Accounts API, accounts can receive the following services. You can add many of these services during account creation.

  • Account aggregation: This service links an advanced account to another account, granting the advanced account full, unrestricted access. It is typically used by marketplaces, multi-brand retailers, or international retailers who need centralized control over nested accounts. If you are an ecommerce platform or channel partner, we recommend using accountManagement instead. When you create an account using account aggregation, the externalAccountId must be omitted.

  • Campaign management: This service models the link between a Merchant Center account and a Google Ads account, giving the Ads account access to product and account data needed to run ad campaigns. The service provider in this case is GOOGLE_ADS and the externalAccountId is the ID of the Google Ads account. This service can also be proposed to an existing account.

  • Comparison shopping: This represents the relationship with a Comparison Shopping Service (CSS) that operates the Merchant Center account.

  • Local listing management: This represents the relationship with a store manager for managing local inventory and listings using a Google business profile.

  • Account management: This service enables the provider to perform administrative actions on the Merchant Center account, such as configuring account settings, managing users, or updating business information. The business can also restrict the access granted. When used during account creation, this service creates an account linked to the provider, which is the recommended approach for ecommerce platforms and channel partners. It can also be proposed to an existing account.

  • Products management: This service allows providers to manage products and related features like data sources and rules. When added during account creation, it's typically in combination with accountManagement or accountAggregation. This service can also be proposed to an existing account.

Handshake

To establish a service, both the account providing the service and the account receiving the service must authorize the connection. This authorization process is called a handshake.

The handshake is a two-step process:

  1. One party proposes a service link.
  2. The other party approves or rejects the proposal.

Once a proposal has been accepted, the service is approved and considered fully established. Any access right conferred to the service provider is now granted to qualified users (See access rights below).

Note that the user creating a proposal, rejecting, or approving it must have ADMIN access rights on the account initiating the process. So if the service provider proposes a service, the user making the proposal must be an ADMIN on the service provider's account and the user accepting or rejecting the proposal must be an ADMIN on the receiving account.

Service-specific handshake behavior

The following is a description of the specific handshake requirements for each individual service:

  • Account aggregation: This service can only be established as part of account creation. The service provider is expected to be an advanced account, and the service is automatically approved since users of the advanced account have full ADMIN access to the account being created.

  • Comparison shopping: This service is automatically approved when added during account creation using createAndConfigure.

  • Campaign management: While this follows the normal handshake process, proposals are made in one system (for example Google Ads) and approvals are done in the other system (for example in Merchant Center or through the Merchant API).

  • Local listing management: For this service, handshake is proposed in a dedicated method and approvals are done in the other system (for example Google business profile). Detailed steps are in the Guide to link a Google business profile.

  • Account management: For this service, the regular handshake process applies when using propose. If the service is added during account creation using createAndConfigure, it is automatically approved.

  • Products management: For this service, the regular handshake process applies (proposed by one party, followed by acceptance from the other).

Access rights

Each service type provides a certain level of access for users of the service provider over the account being serviced:

  • Account aggregation: This service provides full ADMIN rights.

  • Campaign management: This service provides a restricted access right, allowing the associated Ads account to access products and basic account information.

  • Comparison shopping: This service provides, by default, full ADMIN rights. However, the business can restrict the access granted in Merchant Center.

  • Local listing management: This service provides no direct access right. Instead, it enables the listing to synchronize its products with the Merchant Center account.

Important: The access rights described for the following service types apply only to approved service providers. Reach out to our support team if you are a service provider and want to make use of this capability. If you were already previously approved for the accounts.link method for products management in Content API for Shopping, you can use this service in Merchant API without further approvals.

  • Account management: This service provides, by default, full ADMIN rights.

  • Products management: This service provides full ADMIN rights. Note that in the future, this will be limited to only product-related access rights.

How relationships apply for third-party platforms

If you are a third-party platform that manages accounts on behalf of other businesses, the following shows how the different concepts map to your account structure:

  1. Service provider: Your advanced account.
  2. Account receiving the service: A Merchant Center account that represents the business you manage.
  3. Service:
    • accountManagement: This is the recommended service for ecommerce platforms and channel partners creating new accounts on behalf of merchants. It creates an account that the merchant owns, linked to you for management. This aligns with the preferred Merchant Center structure for this use case.
    • accountAggregation: This service links your advanced account to another account. While supported, it is not recommended for ecommerce platforms and channel partners.

For details about how to set up an advanced account and link to new Merchant Center accounts, see Create accounts.