Accounts API 分为一系列资源,可让您更高效地管理 Merchant Center 账号,并更精确地控制账号的各个方面。
本指南介绍了主要变化,并帮助您将现有的账号管理集成从 Content API for Shopping 迁移到 Merchant API。
从一个资源到多个资源
在 Content API for Shopping 中,Account
资源是一个单体对象,其中包含从账号名称和网站网址到用户列表和商家信息的所有内容。
Merchant API 将此资源拆分为几个更小、更专注的资源。此项更改可实现更具针对性且更高效的 API 调用。例如,如果您现在只想更新商家地址,只需向 BusinessInfo
资源发出 PATCH
请求,而无需更新整个 Account
对象。
下面简要说明了 Content API for Shopping Account
资源中的概念如何映射到 Merchant API 中的新资源:
- 核心账号详情(ID、名称、成人内容设置)保留在
Account
资源中。 - 商家信息(地址、电话号码、客户服务)现在由
BusinessInfo
资源进行管理。 - 网站网址和声明所有权由
Homepage
资源处理。 - 用户管理由
User
资源处理。 - 账号关系(指向高级账号、第三方提供商和其他 Google 服务的链接)由
AccountRelationship
和AccountService
资源管理。 - 商家身份属性(例如,黑人经营、女性经营)由
BusinessIdentity
资源管理。 - 服务条款 (ToS) 协议是一项新功能,由
TermsOfService
和TermsOfServiceAgreementState
资源进行管理。
新功能
Merchant API 还引入了 Content API for Shopping 中未提供的全新账号管理功能:
- 服务条款:使用
TermsOfService
和TermsOfServiceAgreementState
资源以程序化方式检索和接受服务条款。 - 通过别名访问账号:使用
providerId~accountAlias
格式访问账号,为管理多个账号的企业提供一种一致的方式来使用自己的账号标识符。
请求
下表对 Content API for Shopping 和 Merchant API 中常见账号管理任务的请求网址进行了整合比较。
请求说明 | Content API for Shopping | Merchant API |
---|---|---|
获取账号 | GET https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/accounts/{accountId} |
GET https://merchantapi.googleapis.com/accounts/v1/accounts/{account} |
按别名获取账号 | 无法直接使用 | GET https://merchantapi.googleapis.com/accounts/v1/accounts/{provider}~{alias} |
列出子账号 | GET https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/accounts |
GET https://merchantapi.googleapis.com/accounts/v1/accounts/{provider}:listSubaccounts |
创建子账号 | POST https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/accounts |
POST https://merchantapi.googleapis.com/accounts/v1/accounts:createAndConfigure |
更新账号数据 | PUT https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/accounts/{accountId} |
针对相应资源的 PATCH 权限。例如,如需更新账号名称,请运行以下命令:PATCH https://merchantapi.googleapis.com/accounts/v1/accounts/{account} |
删除子账号 | DELETE https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/accounts/{accountId} |
DELETE https://merchantapi.googleapis.com/accounts/v1/accounts/{account} |
声明网站所有权 | POST https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/accounts/{accountId}/claimwebsite |
POST https://merchantapi.googleapis.com/accounts/v1/accounts/{account}/homepage:claim |
关联账号 | POST https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/accounts/{accountId}/link |
POST https://merchantapi.googleapis.com/accounts/v1/accounts/{account}/services:propose |
管理核心账号信息
Merchant API 中的 Account
资源包含 Merchant Center 账号的基本详细信息,例如名称、ID 和基本设置。
请求比较
请求说明 | Content API for Shopping | Merchant API |
---|---|---|
获取账号详情 | GET /content/v2.1/{merchantId}/accounts/{accountId} (访问 name 、adult_content 等核心属性) |
GET /accounts/v1/accounts/{account} |
创建子账号 | POST /content/v2.1/{merchantId}/accounts |
POST /accounts/v1/accounts:createAndConfigure |
更新账号详细信息 | PUT /content/v2.1/{merchantId}/accounts/{accountId} (更新核心属性) |
PATCH /accounts/v1/accounts/{account} |
删除子账号 | DELETE /content/v2.1/{merchantId}/accounts/{accountId} |
DELETE /accounts/v1/accounts/{account} |
详细的字段比较
Content API for Shopping (Account ) |
Merchant API (Account ) |
备注 |
---|---|---|
id |
account_id |
数字 ID 现在是仅限输出的字段。主要标识符是资源 name 。 |
name |
account_name |
账号的简明易懂的名称。 |
language |
language_code |
字段名称现在为 language_code 。 |
管理商家信息
您可以使用 BusinessInfo
资源来管理有关您商家的公开信息,例如地址和客户服务联系信息。这取代了 Content API for Shopping 中的 businessInformation
对象。
请求比较
请求说明 | Content API for Shopping | Merchant API |
---|---|---|
获取商家信息 | GET /content/v2.1/{merchantId}/accounts/{accountId} (访问 business_information 属性) |
GET /accounts/v1/accounts/{account}/businessInfo |
更新商家信息 | PUT /content/v2.1/{merchantId}/accounts/{accountId} (更新 business_information 属性) |
PATCH /accounts/v1/accounts/{account}/businessInfo |
详细的字段比较
Content API for Shopping (business_information ) |
Merchant API (BusinessInfo ) |
备注 |
---|---|---|
phone_number |
phone |
该字段现在是 phone ,并使用 google.type.PhoneNumber 。 |
customer_service.url |
customer_service.uri |
字段名称现在为 uri 。 |
管理首页
如需管理您商店的网站网址并执行验证和声明操作,请使用 Homepage
资源。这取代了 Content API for Shopping 中的 websiteUrl
字段和 accounts.claimwebsite
方法。
请求比较
请求说明 | Content API for Shopping | Merchant API |
---|---|---|
获取首页网址 | GET /content/v2.1/{merchantId}/accounts/{accountId} (访问 website_url 属性) |
GET /accounts/v1/accounts/{account}/homepage |
更新首页网址 | PUT /content/v2.1/{merchantId}/accounts/{accountId} (更新 website_url 属性) |
PATCH /accounts/v1/accounts/{account}/homepage |
版权主张首页 | POST /content/v2.1/{merchantId}/accounts/{accountId}/claimwebsite |
POST /accounts/v1/accounts/{account}/homepage:claim |
取消声明首页 | 不可用 | POST /accounts/v1/accounts/{account}/homepage:unclaim |
详细的字段比较
Content API for Shopping (Account ) |
Merchant API (Homepage ) |
备注 |
---|---|---|
website_url |
uri |
商店首页的网址。 |
无法直接使用 | claimed |
一个布尔值字段,如果首页已声明,则为 true 。 |
管理用户
借助 User
资源,您可以管理哪些人可以访问 Merchant Center 账号。这会替换 Account
资源中的 users
数组。一个关键区别在于用户创建流程。在 Merchant API 中,添加用户会发送邀请。用户必须接受邀请才能访问相应账号。
请求比较
请求说明 | Content API for Shopping | Merchant API |
---|---|---|
列出用户 | GET /content/v2.1/{merchantId}/accounts/{accountId} (访问 users 属性) |
GET /accounts/v1/accounts/{account}/users |
创建用户 | PUT /content/v2.1/{merchantId}/accounts/{accountId} (更新 users 属性) |
POST /accounts/v1/accounts/{account}/users |
更新用户 | PUT /content/v2.1/{merchantId}/accounts/{accountId} (更新 users 属性) |
PATCH /accounts/v1/accounts/{account}/users/{email} |
删除用户 | PUT /content/v2.1/{merchantId}/accounts/{accountId} (更新 users 属性) |
DELETE /accounts/v1/accounts/{account}/users/{email} |
详细的字段比较
Content API for Shopping(users 数组对象) |
Merchant API(User 资源) |
备注 |
---|---|---|
email_address |
name (格式为 accounts/{account}/users/{email} ) |
用户的电子邮件地址现在是资源名称的一部分。 |
admin 、order_manager 、reporting_manager 等 |
access_rights |
现在,访问权限已整合到一个重复的枚举字段中。 |
不可用 | state |
一个仅限输出的新字段,用于指明用户是 PENDING 还是 VERIFIED 。 |
管理账号关系和服务
在 Content API for Shopping 中,关系通过 accounts.link
进行管理。
Merchant API 引入了更明确的模型,其中包含 AccountService
和 AccountRelationship
资源,需要进行握手流程(提议和接受)。
请求比较
请求说明 | Content API for Shopping | Merchant API |
---|---|---|
关联账号 | POST /content/v2.1/{merchantId}/accounts/{accountId}/link |
POST /accounts/v1/accounts/{account}/services:propose |
列出关联的账号 | GET /content/v2.1/{merchantId}/accounts/{accountId}/listlinks |
GET /accounts/v1/accounts/{account}/relationships 和GET /accounts/v1/accounts/{account}/services |
详细的字段比较
Content API for Shopping (AccountLink ) |
Merchant API(AccountService 、AccountRelationship ) |
备注 |
---|---|---|
linked_account_id |
provider (位于 AccountService ) |
提供服务的账号的 ID。 |
service |
service_type (位于 AccountService ) |
所提供服务的类型(例如,ACCOUNT_AGGREGATION )。 |
status |
handshake.approval_state (位于 AccountService ) |
链接的状态(例如,PENDING 、ESTABLISHED )。 |
账号税务设置
Content API for Shopping 中的 accounttax
服务在 Merchant API 中不可用。现在,您无需再提供美国销售税相关信息,如需了解详情,请参阅“2025 年的 Merchant Center 商品数据规范更新”。
管理商家身份
您可以使用 BusinessIdentity
资源自行声明与您的商家相关的属性。这取代了 Content API for Shopping 中的 businessIdentity
对象。
请求比较
请求说明 | Content API for Shopping | Merchant API |
---|---|---|
获取商家身份 | GET /content/v2.1/{merchantId}/accounts/{accountId} (访问 business_identity 属性) |
GET /accounts/v1/accounts/{account}/businessIdentity |
更新商家身份信息 | PUT /content/v2.1/{merchantId}/accounts/{accountId} (更新 business_identity 属性) |
PATCH /accounts/v1/accounts/{account}/businessIdentity |
详细的字段比较
Content API for Shopping (business_identity ) |
Merchant API (BusinessIdentity ) |
备注 |
---|---|---|
black_owned.self_identified (布尔值) |
black_owned.identity_declaration (枚举) |
布尔值替换为枚举 (SELF_IDENTIFIES_AS 、DOES_NOT_SELF_IDENTIFY_AS ),以便更明确地声明。这适用于所有身份属性。 |
include_for_promotions (布尔值) |
promotions_consent (枚举) |
将全局布尔值替换为更具描述性的枚举 (PROMOTIONS_CONSENT_GIVEN 、PROMOTIONS_CONSENT_DENIED )。 |
列出账号
在 Content API for Shopping 中,唯一的高级账号类型是“多客户账号 (MCA)”,它公开了一个 accounts.list
方法来列出指定多客户账号的子账号。Merchant API 中的高级账号功能更加强大,支持更广泛的账号类型和关系。为了让高级账号能够顺利迁移,Merchant API 提供了一个与 Content API for Shopping 的 accounts.list
直接对应的 accounts.listSubaccounts
方法。我们即将推出一种新的、更强大的 accounts.list
方法,可实现高级账号过滤。
请求比较
请求说明 | Content API for Shopping | Merchant API |
---|---|---|
列出子账号 | GET /content/v2.1/{merchantId}/accounts |
GET /accounts/v1/accounts/{providerId}:listSubaccounts |
列出所有可访问的账号 | 不可用 | GET /accounts/v1/accounts |
详细的字段比较(请求参数)
Content API for Shopping (accounts.list ) |
Merchant API (accounts.listSubaccounts ) |
备注 |
---|---|---|
merchant_id (路径参数) |
provider (路径参数) |
高级账号的 ID,格式为 accounts/{account} 。 |
max_results |
page_size |
要返回的账号数量上限。 |