Migrate account management

The Accounts API is divided into a collection of resources to allow managing your Merchant Center accounts more efficiently with more precise control across different aspects of your account.

This guide explains the key changes and helps you migrate your existing account management integration from Content API for Shopping to Merchant API.

From one resource to many

In Content API for Shopping, the Account resource was a monolithic object containing everything from the account name and website URL to user lists and business information.

Merchant API splits this into several smaller, more focused resources. This change allows for more targeted and efficient API calls. For example, to update only your business address, you now make a PATCH request to the BusinessInfo resource instead of updating the entire Account object.

Here is a summary of how the concepts from the Content API for Shopping Account resource map to the new resources in the Merchant API:

• Core account details (ID, name, adult content settings) remain in the Account resource.
• Business information (address, phone number, customer service) is now managed by the BusinessInfo resource.
• Website URL and claiming is handled by the Homepage resource.
• User management is handled by the User resource.
• Account relationships (links to advanced accounts, third-party providers, and other Google services) are managed by the AccountRelationship and AccountService resources.
• Business identity attributes (for example, black-owned, women-owned) are managed by the BusinessIdentity resource.
• Terms of Service (ToS) agreements, a new feature, are managed by the TermsOfService and TermsOfServiceAgreementState resources.

New capabilities

Merchant API also introduces new capabilities for account management that were not available in Content API for Shopping:

• Terms of Service: Programmatically retrieve and accept Terms of Service using the TermsOfService and TermsOfServiceAgreementState resources.
• Account Access by Alias: Access accounts using a providerId~accountAlias format, providing a consistent way for businesses that manage multiple accounts to use their own account identifiers.

Requests

This table provides a consolidated comparison of the request URLs for common account management tasks between Content API for Shopping and Merchant API.

Request description	Content API for Shopping	Merchant API
Get account	GET https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/accounts/{accountId}	GET https://merchantapi.googleapis.com/accounts/v1/accounts/{account}
Get account by alias	Not directly available	GET https://merchantapi.googleapis.com/accounts/v1/accounts/{provider}~{alias}
List sub-accounts	GET https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/accounts	GET https://merchantapi.googleapis.com/accounts/v1/accounts/{provider}:listSubaccounts
Create sub-account	POST https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/accounts	POST https://merchantapi.googleapis.com/accounts/v1/accounts:createAndConfigure
Update account data	PUT https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/accounts/{accountId}	PATCH on the appropriate resource. For example, to update the account name: PATCH https://merchantapi.googleapis.com/accounts/v1/accounts/{account}
Delete sub-account	DELETE https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/accounts/{accountId}	DELETE https://merchantapi.googleapis.com/accounts/v1/accounts/{account}
Claim website	POST https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/accounts/{accountId}/claimwebsite	POST https://merchantapi.googleapis.com/accounts/v1/accounts/{account}/homepage:claim
Link accounts	POST https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/accounts/{accountId}/link	POST https://merchantapi.googleapis.com/accounts/v1/accounts/{account}/services:propose

Manage core account information

The Account resource in Merchant API contains the essential details of a Merchant Center account, such as its name, ID, and basic settings.

Request comparison

Request description	Content API for Shopping	Merchant API
Get account details	GET /content/v2.1/{merchantId}/accounts/{accountId} (accessing core attributes like name, adult_content)	GET /accounts/v1/accounts/{account}
Create a sub-account	POST /content/v2.1/{merchantId}/accounts	POST /accounts/v1/accounts:createAndConfigure
Update account details	PUT /content/v2.1/{merchantId}/accounts/{accountId} (updating core attributes)	PATCH /accounts/v1/accounts/{account}
Delete a sub-account	DELETE /content/v2.1/{merchantId}/accounts/{accountId}	DELETE /accounts/v1/accounts/{account}

Detailed field comparison

Content API for Shopping (Account)	Merchant API (Account)	Notes
id	account_id	The numeric ID is now an output-only field. The primary identifier is the resource name.
name	account_name	The human-readable name of the account.
language	language_code	The field name is now language_code.

Manage business information

Use the BusinessInfo resource to manage public information about your business, such as your address and customer service contacts. This replaces the businessInformation object in Content API for Shopping.

Request comparison

Request description	Content API for Shopping	Merchant API
Get business information	GET /content/v2.1/{merchantId}/accounts/{accountId} (accessing the business_information attribute)	GET /accounts/v1/accounts/{account}/businessInfo
Update business information	PUT /content/v2.1/{merchantId}/accounts/{accountId} (updating the business_information attribute)	PATCH /accounts/v1/accounts/{account}/businessInfo

Detailed field comparison

Content API for Shopping (business_information)	Merchant API (BusinessInfo)	Notes
phone_number	phone	The field is now phone and uses google.type.PhoneNumber.
customer_service.url	customer_service.uri	The field name is now uri.

Manage your homepage

To manage your store's website URL and perform verification and claiming, use the Homepage resource. This replaces the websiteUrl field and the accounts.claimwebsite method from Content API for Shopping.

Request comparison

Request description	Content API for Shopping	Merchant API
Get homepage URL	GET /content/v2.1/{merchantId}/accounts/{accountId} (accessing the website_url attribute)	GET /accounts/v1/accounts/{account}/homepage
Update homepage URL	PUT /content/v2.1/{merchantId}/accounts/{accountId} (updating the website_url attribute)	PATCH /accounts/v1/accounts/{account}/homepage
Claim homepage	POST /content/v2.1/{merchantId}/accounts/{accountId}/claimwebsite	POST /accounts/v1/accounts/{account}/homepage:claim
Unclaim homepage	Not available	POST /accounts/v1/accounts/{account}/homepage:unclaim

Detailed field comparison

Content API for Shopping (Account)	Merchant API (Homepage)	Notes
website_url	uri	The URL of the store's homepage.
Not directly available	claimed	A boolean field that is true if the homepage is claimed.

Manage users

The User resource lets you manage who can access a Merchant Center account. This replaces the users array within the Account resource. A key difference is the user creation process. In Merchant API, adding a user sends an invitation. The user must accept the invitation before they can access the account.

Request comparison

Request description	Content API for Shopping	Merchant API
List users	GET /content/v2.1/{merchantId}/accounts/{accountId} (accessing the users attribute)	GET /accounts/v1/accounts/{account}/users
Create a user	PUT /content/v2.1/{merchantId}/accounts/{accountId} (updating the users attribute)	POST /accounts/v1/accounts/{account}/users
Update a user	PUT /content/v2.1/{merchantId}/accounts/{accountId} (updating the users attribute)	PATCH /accounts/v1/accounts/{account}/users/{email}
Delete a user	PUT /content/v2.1/{merchantId}/accounts/{accountId} (updating the users attribute)	DELETE /accounts/v1/accounts/{account}/users/{email}

Detailed field comparison

Content API for Shopping (users array object)	Merchant API (User resource)	Notes
email_address	name (in format accounts/{account}/users/{email})	The user's email is now part of the resource name.
admin, order_manager, reporting_manager, etc.	access_rights	Access rights are now consolidated into a repeated enum field.
Not available	state	A new output-only field indicating if the user is PENDING or VERIFIED.

Manage account relationships and services

In Content API for Shopping, relationships were managed with accounts.link. Merchant API introduces a more explicit model with AccountService and AccountRelationship resources, requiring a handshake process (propose and accept).

Request comparison

Request description	Content API for Shopping	Merchant API
Link accounts	POST /content/v2.1/{merchantId}/accounts/{accountId}/link	POST /accounts/v1/accounts/{account}/services:propose
List linked accounts	GET /content/v2.1/{merchantId}/accounts/{accountId}/listlinks	GET /accounts/v1/accounts/{account}/relationships and GET /accounts/v1/accounts/{account}/services

Detailed field comparison

Content API for Shopping (AccountLink)	Merchant API (AccountService, AccountRelationship)	Notes
linked_account_id	provider (in AccountService)	The ID of the account providing the service.
service	service_type (in AccountService)	The type of service being provided (e.g., ACCOUNT_AGGREGATION).
status	handshake.approval_state (in AccountService)	The status of the link (e.g., PENDING, ESTABLISHED).

Account tax settings

The accounttax service from the Content API for Shopping is not available in Merchant API. It is no longer required to provide US sales tax, for more information see Merchant Center product data specification update 2025.

Manage business identity

Use the BusinessIdentity resource to self-declare attributes about your business. This replaces the businessIdentity object in Content API for Shopping.

Request comparison

Request description	Content API for Shopping	Merchant API
Get business identity	GET /content/v2.1/{merchantId}/accounts/{accountId} (accessing the business_identity attribute)	GET /accounts/v1/accounts/{account}/businessIdentity
Update business identity	PUT /content/v2.1/{merchantId}/accounts/{accountId} (updating the business_identity attribute)	PATCH /accounts/v1/accounts/{account}/businessIdentity

Detailed field comparison

Content API for Shopping (business_identity)	Merchant API (BusinessIdentity)	Notes
black_owned.self_identified (boolean)	black_owned.identity_declaration (enum)	The boolean is replaced by an enum (SELF_IDENTIFIES_AS, DOES_NOT_SELF_IDENTIFY_AS) for more explicit declaration. This applies to all identity attributes.
include_for_promotions (boolean)	promotions_consent (enum)	A global boolean is replaced by a more descriptive enum (PROMOTIONS_CONSENT_GIVEN, PROMOTIONS_CONSENT_DENIED).

List accounts

In Content API for Shopping the only type of advanced account was a 'Multi-Client Account (MCA)' and it exposed an accounts.list method to list the sub-accounts of the given Multi-Client Account. Advanced accounts in Merchant API are much more powerful, allowing a broader range of account types and relationships. To allow a straightforward migration for advanced accounts, Merchant API provides a direct equivalent to Content API for Shopping's accounts.list as a accounts.listSubaccounts method. We are introducing a new, more powerful accounts.list method that allows advanced account filtering.

Request comparison

Request description	Content API for Shopping	Merchant API
List sub-accounts	GET /content/v2.1/{merchantId}/accounts	GET /accounts/v1/accounts/{providerId}:listSubaccounts
List all accessible accounts	Not available	GET /accounts/v1/accounts

Detailed field comparison (Request parameters)

Content API for Shopping (accounts.list)	Merchant API (accounts.listSubaccounts)	Notes
merchant_id (path parameter)	provider (path parameter)	The ID of the advanced account in the format accounts/{account}.
max_results	page_size	The maximum number of accounts to return.