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
Accountresource. - Business information
(address, phone
number, customer service) is now managed by the
BusinessInforesource. - Website URL and claiming
is handled by the
Homepageresource. - User management
is handled by the
Userresource. - Account relationships
(links to advanced accounts, third-party providers, and other Google
services) are managed by the
AccountRelationshipandAccountServiceresources. - Business identity attributes
(for example,
black-owned, women-owned) are managed by the
BusinessIdentityresource. - Terms of Service (ToS) agreements, a new feature, are managed by the
TermsOfServiceandTermsOfServiceAgreementStateresources.
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
TermsOfServiceandTermsOfServiceAgreementStateresources. - Account Access by Alias:Access accounts using a
providerId~accountAliasformat, 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. |
