Migrate from v1beta to v1

This guide helps you migrate from Merchant API v1beta to v1 , the first version for General Availability. The v1 version introduces several updates and a few changes that might require code updates. These changes are designed to simplify the API and improve management of your Merchant Center account.

Key differences

Here are the most important changes to be aware of when migrating from v1beta to v1 :

• One-time registration of at least one API developer to use Merchant API:You will need to call the registerGcp method (only once for each Google Cloud project used for authentication) to provide your contact details, which lets you to use the API and to receive updates and announcements related to Merchant API. You won't be able to use any v1 or v1alpha API until this step is completed. For directions, see Register as a developer
• Product.attributes renamed: The Product.attributes field has been renamed to Product.productAttributes .
• Product-level tax information removal:The taxes and taxCategory fields have been removed from the Product.productAttributes object. Check the Google Merchant Center Help article on tax for more info
• Changes to the GTIN field:The gtin field in the Product.productAttributes object has been renamed to gtins to better reflect that it can hold multiple values. The gtin field in the OrderTrackingSignals.lineItemDetails object is now an array and has been renamed to gtins as well.
• Channel field removal:The channel field has been removed from products, product inputs, and data sources. A new boolean field, legacyLocal , has been introduced to clearly designate products sold exclusively in physical stores. Note: The legacyLocal field is an auxiliary field to help the migration and will eventually be deprecated once Online and Local marketing methods can be fully targeted with a single product source. Check the table in the following section for more informations.
• New fields for regional and local inventory attributes:
  • All RegionalInventory fields except name , account and region are now wrapped under a new object called regionalInventoryAttributes . For example, the RegionalInventory.price attribute is now under RegionalInventory.regionalInventoryAttributes.price .
  • All LocalInventory fields except name , account and storeCode are now wrapped under a new object called localInventoryAttributes . For example, the LocalInventory.price attribute is now under LocalInventory.localInventoryAttributes.price .
• Removal of customAttributes from regional and local inventories:The customAttributes field has been removed from both RegionalInventory and LocalInventory resources.
• Refined account creation:The redundant users field has been removed from the CreateAndConfigureAccountRequest . Use the singular user field to associate an initial user with a new account.
• Certain attribute types were changed from strings to enums:Some fields within Product and Inventory resources with defined short list of values were changed from string type to enum type for better data validation (for example, the Product.ProductAttributes.condition field is now an enum ).
• Online return policy update method removal:The onlineReturnPolicy.update method is removed in v1 . Create an online return policy using onlineReturnPolicy.create method instead.

How to migrate

The v1beta version of the Merchant API is scheduled to be sunset on February 28, 2026. For more information on the deprecation schedule, see the Merchant API versioning guide .

• Your first step in migrating is to perform a one-time developer registration (See Register as a developer ). You must call the registerGcp method for each Google Cloud project you use for authentication before any v1 methods will work.

• Regardless on how you call the APIs (with REST, gRPC or by using client libraries ), you can migrate in stages. This means you can update and migrate your code one API at a time (for example, moving the Products API to v1 while keeping the Accounts API on v1beta ) without having to update your entire integration at once.

Detailed field changes

This table provides a detailed comparison of the fields that have changed between the v1beta and v1 versions.