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.

v1beta	v1	Description
Product.gtin	Product.gtins	The field for GTINs has been renamed.
Product.taxes	Removed	The taxes field has been removed
Product.taxCategory	Removed	The taxCategory field has been removed
Product.channel	Removed	The channel field has been removed. Use the legacyLocal field for local use cases.
Product.attributes	Product.productAttributes	The attributes field has been renamed to productAttributes.
availability, condition, gender, includedDestinations and excludedDestinations in Product fields are represented as strings (or array of strings)	These fields are now enums (or array of enums)	Fields with defined short list of values were changed from string type to enum.
price, salePrice, salePriceEffectiveDate and availability in RegionalInventory	Moved to RegionalInventory.regionalInventoryAttributes	These fields have been moved under regionalInventoryAttributes.
RegionalInventory.availability field is a string	RegionalInventory.regionalInventoryAttributes.availability is now an enums	Availability changed type from string to enum.
price, salePrice, salePriceEffectiveDate, availability, quantity, pickupMethod, pickupSla and instoreProductLocation in LocalInventory	Moved to LocalInventory.localInventoryAttributes	These fields have been moved under localInventoryAttributes.
LocalInventory.availability field is a string	LocalInventory.localInventoryAttributes.availability is now an enums	Availability changed type from string to enum.
LocalInventory.customAttributes	Removed	Custom attributes are no longer supported for local inventory.
RegionalInventory.customAttributes	Removed	Custom attributes are no longer supported for regional inventory.
ProductInput.channel	Removed	The channel field has been removed. Use the legacyLocal field for local use cases.
DataSource.channel	Removed	The channel field has been removed. Use the legacyLocal field for local use cases.
Not available	ProductInput.legacyLocal	A new boolean field to indicate that a product can only target local marketing methods. The product resource ID will have "local~" prefix.
Not available	Product.legacyLocal	A new boolean field to indicate that a product is sold only in local stores and is not available for online purchase.
Not available	DataSource.legacyLocal	A new boolean field to indicate that a data source contains products sold only in local stores.
OrderTrackingSignals.LineItemDetails.gtin	OrderTrackingSignals.LineItemDetails.gtins	The gtin field has been renamed to gtins and it's now an array of strings (instead of a string).
CreateAndConfigureAccountRequest.users	Removed	The users field has been removed. Use the user field to add the initial administrator to the account.