遷移帳戶管理

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 中的新資源：

新功能

Merchant API 也推出 Content API for Shopping 沒有的新帳戶管理功能：

  • 服務條款：使用 TermsOfService 和 TermsOfServiceAgreementState 資源，以程式輔助方式擷取及接受服務條款。
  • 建立帳戶：accounts.createAndConfigure 方法現在支援建立具有關係 (例如 accountManagement) 的帳戶、設定 alias，以及使用 user.verificationMailSettings.verificationMailMode 欄位抑制電子郵件驗證，改用新的 accounts.verifySelf 方法進行 API 驗證。
  • 透過別名存取帳戶：使用 providerId~accountAlias 格式存取帳戶，讓管理多個帳戶的商家能以一致的方式使用自己的帳戶 ID。

要求

下表整合比較 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 現在是僅限輸出的欄位。主要 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)。

帳戶稅金設定

Merchant API 不提供 Content API for Shopping 的 accounttax 服務。您不再需要提供美國銷售稅，詳情請參閱「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 要傳回的帳戶數量上限。
上一頁
Refactor code for concurrent requests
下一頁
Migrate accountstatuses to Account Issues