從 v1beta 遷移至 v1

本指南可協助你從 Merchant API v1beta 遷移至 v1，這是第一個正式發布的版本。v1 版本推出多項更新，以及幾項可能需要更新程式碼的變更。這些異動旨在簡化 API，並提升 Merchant Center 帳戶的管理效率。

主要差異

從 v1beta 遷移至 v1 時，請留意下列重大異動：

• 至少註冊一位 API 開發人員，即可使用 Merchant API： 您需要呼叫 registerGcp 方法 (每個用於驗證的 Google Cloud 專案只需呼叫一次)，提供聯絡資訊，即可使用 API，並接收 Merchant API 相關的最新消息和公告。 完成這個步驟後，您才能使用任何 v1 或 v1alpha API。如需操作說明，請參閱「註冊成為開發人員」一文。
• Product.attributes已重新命名：Product.attributes 欄位已重新命名為 Product.productAttributes。
• 移除產品層級的稅務資訊：已從 Product.productAttributes 物件中移除 taxes 和 taxCategory 欄位。如需更多資訊，請參閱這篇 Google Merchant Center 說明文章。
• GTIN 欄位異動： Product.productAttributes 物件中的 gtin 欄位已重新命名為 gtins，以更準確地反映該欄位可保留多個值。OrderTrackingSignals.lineItemDetails 物件中的 gtin 欄位現在是 array，且已重新命名為 gtins。
• 移除管道欄位：channel 欄位已從產品、產品輸入內容和資料來源中移除。我們新增了布林值欄位「legacyLocal」，可清楚標示僅在實體商店販售的產品。注意：legacyLocal 欄位是輔助欄位，可協助遷移，一旦線上和店面行銷方法能以單一產品來源為目標，這個欄位最終就會遭到淘汰。詳情請參閱下節的表格。
• 區域和店面商品目錄屬性的新欄位：
  • 除了 name、account 和 region 以外，所有 RegionalInventory 欄位現在都會包裝在名為 regionalInventoryAttributes 的新物件下。舉例來說，RegionalInventory.price 屬性現在位於 RegionalInventory.regionalInventoryAttributes.price 底下。
  • 除了 name、account 和 storeCode 以外，所有 LocalInventory 欄位現在都會包裝在名為 localInventoryAttributes 的新物件下。舉例來說，LocalInventory.price 屬性現在位於 LocalInventory.localInventoryAttributes.price 底下。
• 從區域和店面商品目錄資料中移除 customAttributes：customAttributes 欄位已從 RegionalInventory 和 LocalInventory 資源中移除。
• 簡化帳戶建立流程：已從 CreateAndConfigureAccountRequest 移除多餘的 users 欄位。使用單一的 user 欄位，將初始使用者與新帳戶建立關聯。
• 部分屬性類型已從字串變更為列舉：Product 和 Inventory 資源中定義的簡短值清單內的部分欄位，已從 string 類型變更為 enum 類型，以利進行資料驗證 (例如，Product.ProductAttributes.condition 欄位現在是 enum)。
• 移除線上退貨政策更新方法：v1 中已移除 onlineReturnPolicy.update 方法。請改用 onlineReturnPolicy.create 方法建立線上退貨政策。

如何遷移

Merchant API 的 v1beta 版本預計於 2026 年 2 月 28 日停用。如要進一步瞭解淘汰時間表，請參閱商家 API 版本管理指南。

• 如要開始遷移，請先完成一次性開發人員註冊 (請參閱「註冊成為開發人員」)。您必須先為用於驗證的每個 Google Cloud 專案呼叫 registerGcp 方法，才能使用任何 v1 方法。

• 無論您如何呼叫 API (使用 REST、gRPC 或用戶端程式庫)，都可以分階段遷移。也就是說，您可以一次更新及遷移一個 API 的程式碼 (例如將 Products API 移至 v1，同時將 Accounts API 留在 v1beta)，不必一次更新整個整合。

詳細欄位變更

下表詳細比較 v1beta 和 v1 版本之間變更的欄位。

v1beta	v1	說明
Product.gtin	Product.gtins	GTIN 欄位已重新命名。
Product.taxes	已移除	已移除「taxes」欄位
Product.taxCategory	已移除	已移除「taxCategory」欄位
Product.channel	已移除	已移除「channel」欄位，針對本機用途，請使用 legacyLocal 欄位。
Product.attributes	Product.productAttributes	「attributes」欄位已重新命名為「productAttributes」。
Product 欄位中的 availability、condition、gender、includedDestinations 和 excludedDestinations 欄位會以 strings (或 strings 的 array) 表示	這些欄位現在是 enums (或 enums 的 array)	定義值簡短清單的欄位已從 string 類型變更為 enum。
price、salePrice、salePriceEffectiveDate 和 availability (位於 RegionalInventory 中)	已移至「RegionalInventory.regionalInventoryAttributes」	這些欄位已移至 regionalInventoryAttributes 下。
「RegionalInventory.availability」欄位為 string	RegionalInventory.regionalInventoryAttributes.availability 現在是enums	「供應情形」已從「string」變更為「enum」。
price、salePrice、salePriceEffectiveDate、availability、quantity、pickupMethod、pickupSla 和 instoreProductLocation (位於 LocalInventory)	已移至「LocalInventory.localInventoryAttributes」	這些欄位已移至 localInventoryAttributes 下。
「LocalInventory.availability」欄位為 string	LocalInventory.localInventoryAttributes.availability 現在是enums	「供應情形」已從「string」變更為「enum」。
LocalInventory.customAttributes	已移除	店面商品目錄不再支援自訂屬性。
RegionalInventory.customAttributes	已移除	系統已不再支援區域廣告空間的自訂屬性。
ProductInput.channel	已移除	已移除「channel」欄位，針對本機用途，請使用 legacyLocal 欄位。
DataSource.channel	已移除	已移除「channel」欄位，針對本機用途，請使用 legacyLocal 欄位。
不適用	ProductInput.legacyLocal	新的布林值欄位，用於指出產品只能指定區域行銷方式。產品資源 ID 會加上「local~」前置字元。
不適用	Product.legacyLocal	新的布林值欄位，用於指出產品僅在當地商店銷售，無法在線上購買。
不適用	DataSource.legacyLocal	新的布林值欄位，用來指出資料來源是否包含僅限店面販售的產品。
OrderTrackingSignals.LineItemDetails.gtin	OrderTrackingSignals.LineItemDetails.gtins	「gtin」欄位已重新命名為「gtins」，現在是字串陣列 (而非字串)。
CreateAndConfigureAccountRequest.users	已移除	已移除「users」欄位，使用 user 欄位為帳戶新增初始管理員。