Migrate account management

  • Merchant API improves upon Content API v2.1 with a granular resource structure, unified account services, and a simplified URL structure.

  • Key resources like account, businessDetails, user, homepage, and program are hierarchically organized for better clarity and management.

  • Account management is streamlined with a dedicated accounts resource and features enhanced program/user management, structured business information, and homepage claiming.

  • Merchant API complies with Google API guidelines, ensuring consistency and best practices for developers.

  • A detailed comparison table highlights the differences between Content API v2.1 resources and their Merchant API counterparts, aiding in migration efforts.

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:

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.