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](https://developers.google.com/shopping-content/reference/rest/v2.1/accounts#resource:-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](https://developers.google.com/merchant/api/guides/accounts/create-accounts). - **Account aggregation** : This service (`accountAggregation`) links a [multi-client advanced account](https://support.google.com/merchants/answer/188487) to a sub-account, granting the advanced account full, unrestricted access and making the sub-account visible in the Merchant Center UI. The Merchant Center UI automatically converts accounts to advanced accounts with `accountAggregation` for store builders (ecommerce platforms), channel partners, marketplaces, multi-brand retailers, and international retailers when creating new sub-accounts. If you are an agency, use `accountManagement` instead. When you [create an account](https://developers.google.com/merchant/api/guides/accounts/create-accounts) 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. > [!NOTE] > **Note:** For Retailers/ Marketplaces using [Commerce Media Network](https://support.google.com/google-ads/answer/16030900) through Google Ads accounts: - This service allows for the creation of partner specific product filters when running Commerce Media Network campaigns. - At this time, you must use the Alpha version of the Accounts sub-API. - Usage of this feature requires specific GMC allowlisting. Reach out to your Google Ads account management team for further details. - **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 (`accountManagement`) enables the provider to perform administrative actions on a standalone external 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](https://developers.google.com/merchant/api/guides/accounts/create-accounts), this service creates a standalone account linked to the provider. It can also be proposed to an existing account. Agencies that use this service type can see the accounts they manage in Merchant Center for Agencies. Store builders and channel partners can use the Merchant API to pull information about merchants they manage through `accountManagement`. - **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. - **UCP checkout management** (`v1alpha`, limited access): The `ucpCheckoutManagement` service lets an approved service provider manage UCP checkout integrations, settings, and program participation on behalf of a merchant. This service can only be proposed to or approved by an existing Merchant Center account. *Note:* UCP checkout is an alpha feature with limited access. Learn more about service providers and UCP checkout in [Merchant Center for service providers](https://developers.google.com/merchant/3p/overview). ## 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](https://developers.google.com/merchant/api/guides/accounts/relationships#access-rights) below). > [!IMPORTANT] > **Important:** Cross-account access rights can take up to 60 seconds to propagate after you call `accounts.services.approve`. If subsequent Merchant API requests to the linked account return `401 UNAUTHENTICATED`, retry with exponential backoff. Note that the user creating a proposal, rejecting, or approving it must have `ADMIN` [access rights](https://developers.google.com/merchant/api/reference/rest/accounts_v1/accounts.users#accessright) 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. The following samples demonstrate how to propose an account service: ### Java import com.google.api.gax.core.FixedCredentialsProvider; import com.google.auth.oauth2.GoogleCredentials; import com.google.shopping.merchant.accounts.v1.AccountName; import com.google.shopping.merchant.accounts.v1.AccountService; import com.google.shopping.merchant.accounts.v1.AccountServicesServiceClient; import com.google.shopping.merchant.accounts.v1.AccountServicesServiceSettings; import com.google.shopping.merchant.accounts.v1.ProductsManagement; import com.google.shopping.merchant.accounts.v1.ProposeAccountServiceRequest; import shopping.merchant.samples.utils.Authenticator; /** This class demonstrates how to propose a service to an existing Merchant Center account. */ public class ProposeServiceSample { public static void proposeService(long accountId, long providerId, String externalAccountId) throws Exception { // Obtains OAuth token based on the user's configuration. // The user that authenticates should have access to the account. GoogleCredentials credential = new Authenticator().authenticate(); // Creates service settings using the credentials retrieved above. AccountServicesServiceSettings accountServicesServiceSettings = AccountServicesServiceSettings.newBuilder() .setCredentialsProvider(FixedCredentialsProvider.create(credential)) .build(); // Calls the API and catches and prints any network failures/errors. try (AccountServicesServiceClient accountServicesServiceClient = AccountServicesServiceClient.create(accountServicesServiceSettings)) { // The service to be proposed. // This sample shows how to propose product management. // For more information about the different services, see: // https://developers.google.com/merchant/api/guides/accounts/services AccountService accountService = AccountService.newBuilder() .setProductsManagement(ProductsManagement.newBuilder().build()) .setExternalAccountId(externalAccountId) .build(); String accountName = AccountName.newBuilder().setAccount(String.valueOf(accountId)).build().toString(); ProposeAccountServiceRequest request = ProposeAccountServiceRequest.newBuilder() .setParent(accountName) .setProvider("accounts/" + providerId) .setAccountService(accountService) .build(); System.out.println("Sending Propose Service request:"); AccountService response = accountServicesServiceClient.proposeAccountService(request); System.out.println("Proposed Service below"); System.out.println(response); } catch (Exception e) { System.out.println(e); } } public static void main(String[] args) throws Exception { // The ID of the account to propose the service to. long accountId = 123L; // This is the provider ID of the e-commerce platform. long providerId = 456L; // An external ID that uniquely identifies the account service. String externalAccountId = "ext-acc-id-123"; proposeService(accountId, providerId, externalAccountId); } } ### PHP require_once __DIR__ . '/../../../../vendor/autoload.php'; require_once __DIR__ . '/../../../Authentication/Authentication.php'; require_once __DIR__ . '/../../../Authentication/Config.php'; use Google\ApiCore\ApiException; use Google\Shopping\Merchant\Accounts\V1\AccountAggregation; use Google\Shopping\Merchant\Accounts\V1\AccountService; use Google\Shopping\Merchant\Accounts\V1\Client\AccountServicesServiceClient; use Google\Shopping\Merchant\Accounts\V1\ProposeAccountServiceRequest; /** * This class demonstrates how to propose an account service. */ class ProposeAccountServiceSample { /** * A helper function to create the account name string. * * @param string $accountId The ID of the account. * * @return string The account name has the format: `accounts/{account_id}` */ private static function toAccountName(string $accountId): string { return sprintf('accounts/%s', $accountId); } /** * Proposes a new account service. * * @param array $config The configuration data used for authentication and * getting the account ID. * @param string $providerId The ID of the provider account. */ public static function proposeAccountService( array $config, string $providerId ): void { // Gets the OAuth credentials to make the request. $credentials = Authentication::useServiceAccountOrTokenFile(); // Creates options containing credentials for the client to use. $options = ['credentials' => $credentials]; // Creates a client. $accountServicesServiceClient = new AccountServicesServiceClient($options); // Calls the API and catches and prints any network failures/errors. try { $accountAggregation = new AccountAggregation(); $accountService = (new AccountService()) ->setAccountAggregation($accountAggregation); $request = (new ProposeAccountServiceRequest()) ->setParent(self::toAccountName($config['accountId'])) ->setProvider(self::toAccountName($providerId)) ->setAccountService($accountService); print "Sending Propose AccountService request\n"; $response = $accountServicesServiceClient->proposeAccountService($request); print "Proposed AccountService below\n"; print $response->serializeToJsonString(true) . PHP_EOL; } catch (ApiException $e) { printf("An error has occurred: %s%s", $e->getMessage(), PHP_EOL); } } /** * Helper to execute the sample. */ public function callSample(): void { $config = Config::generateConfig(); // Update this with the Merchant Center provider ID you want to get the // relationship for. $providerId = 111; self::proposeAccountService($config, $providerId); } } // Run the script $sample = new ProposeAccountServiceSample(); $sample->callSample(); ### Python """This class demonstrates how to propose an account service.""" from examples.authentication import configuration from examples.authentication import generate_user_credentials from google.shopping.merchant_accounts_v1 import AccountAggregation from google.shopping.merchant_accounts_v1 import AccountService from google.shopping.merchant_accounts_v1 import AccountServicesServiceClient from google.shopping.merchant_accounts_v1 import ProposeAccountServiceRequest _ACCOUNT = configuration.Configuration().read_merchant_info() _PARENT = f"accounts/{_ACCOUNT}" def propose_account_service(provider_id: int) -> None: """Proposes an account service. Args: provider_id: The Merchant Center ID of the provider. """ # Gets OAuth Credentials. credentials = generate_user_credentials.main() # Creates a client. client = AccountServicesServiceClient(credentials=credentials) # Creates the provider resource name from the provider ID. provider = f"accounts/{provider_id}" # Creates an AccountService object. # For this request, only `account_aggregation` is needed. account_service = AccountService() account_service.account_aggregation = AccountAggregation() # Creates the request. request = ProposeAccountServiceRequest( parent=_PARENT, provider=provider, account_service=account_service, ) # Makes the request and catches and prints any error messages. try: print("Sending Propose AccountService request") response = client.propose_account_service(request=request) print("Proposed AccountService below") print(response) except RuntimeError as e: print(e) if __name__ == "__main__": # Update this with the Merchant Center provider ID you want to get the # relationship for. provider_id_ = 111 propose_account_service(provider_id_) ## 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](https://developers.google.com/merchant/api/guides/accounts/link-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). - **UCP checkout management** (`v1alpha`, limited access): For this service, the merchant can complete the handshake through the Google-hosted account linking dialog in the service provider's portal, or using the standard handshake process (`propose` followed by `approve`). For integration details, see the [Merchant Center service providers documentation](https://developers.google.com/merchant/3p/overview). ## 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](https://developers.google.com/merchant/api/support/get-help) 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. - **UCP checkout management** (`v1alpha`, limited access): This service provides full `ADMIN` rights. Note that in the future, this will be limited to only UCP checkout-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](https://support.google.com/merchants/answer/188487). 2. **Account receiving the service**: A Merchant Center account that represents the business you manage. 3. **Service** : - `accountAggregation`: Used by store builders (ecommerce platforms), channel partners, marketplaces, and multi-brand retailers creating new sub-accounts on behalf of merchants. The Merchant Center UI automatically configures store builders and channel partners as advanced accounts with `accountAggregation`, allowing them to view and manage sub-accounts in the Merchant Center UI. - `accountManagement`: Used by agencies creating or linking to standalone client accounts owned by the merchant, which they can view in Merchant Center for Agencies. Other types of service providers use the [`accounts.list`](https://developers.google.com/merchant/api/reference/rest/accounts_v1/accounts/list) method in the Merchant API to view linked account information. For details about how to set up an [advanced account](https://support.google.com/merchants/answer/188487) and link to new Merchant Center accounts, see [Create accounts](https://developers.google.com/merchant/api/guides/accounts/create-accounts).