Migrer de v1beta à v1

Ce guide vous aide à migrer de l'API Merchant v1beta vers v1, la première version disponible à l'échelle générale. La version v1 introduit plusieurs mises à jour et quelques modifications qui peuvent nécessiter des mises à jour du code. Ces modifications visent à simplifier l'API et à améliorer la gestion de votre compte Merchant Center.

Principales différences

Voici les modifications les plus importantes à connaître lorsque vous migrez de v1beta vers v1 :

• Enregistrement unique d'au moins un développeur d'API pour utiliser l'API Merchant : vous devrez appeler la méthode registerGcp (une seule fois pour chaque projet Google Cloud utilisé pour l'authentification) afin de fournir vos coordonnées. Cela vous permettra d'utiliser l'API et de recevoir des informations et des annonces concernant l'API Merchant. Vous ne pourrez pas utiliser les API v1 ni v1alpha tant que cette étape n'aura pas été effectuée. Pour obtenir des instructions, consultez S'inscrire comme développeur.
• Product.attributes renommé : le champ Product.attributes a été renommé Product.productAttributes.
• Suppression des informations fiscales au niveau du produit : les champs taxes et taxCategory ont été supprimés de l'objet Product.productAttributes. Pour en savoir plus, consultez l'article du Centre d'aide Google Merchant Center sur les taxes.
• Modifications apportées au champ GTIN : le champ gtin de l'objet Product.productAttributes a été renommé gtins pour mieux refléter le fait qu'il peut contenir plusieurs valeurs. Le champ gtin de l'objet OrderTrackingSignals.lineItemDetails est désormais un array et a également été renommé en gtins.
• Suppression du champ "Canal" : le champ channel a été supprimé des produits, des entrées de produit et des sources de données. Un nouveau champ booléen, legacyLocal, a été introduit pour désigner clairement les produits vendus exclusivement dans les magasins physiques. Remarque : Le champ legacyLocal est un champ auxiliaire destiné à faciliter la migration. Il sera à terme obsolète une fois que les méthodes de marketing en ligne et en magasin pourront être entièrement ciblées avec une seule source de produits. Pour en savoir plus, consultez le tableau de la section suivante.
• Nouveaux champs pour les attributs d'inventaire régional et local :
  • Tous les champs RegionalInventory, à l'exception de name, account et region, sont désormais regroupés sous un nouvel objet appelé regionalInventoryAttributes. Par exemple, l'attribut RegionalInventory.price se trouve désormais sous RegionalInventory.regionalInventoryAttributes.price.
  • Tous les champs LocalInventory, à l'exception de name, account et storeCode, sont désormais regroupés sous un nouvel objet appelé localInventoryAttributes. Par exemple, l'attribut LocalInventory.price se trouve désormais sous LocalInventory.localInventoryAttributes.price.
• Suppression de customAttributes des inventaires régionaux et locaux : le champ customAttributes a été supprimé des ressources RegionalInventory et LocalInventory.
• Création de compte affinée : le champ users redondant a été supprimé de CreateAndConfigureAccountRequest. Utilisez le champ user au singulier pour associer un premier utilisateur à un nouveau compte.
• Certains types d'attributs sont passés de chaînes à des énumérations : certains champs des ressources Product et Inventory avec une liste de valeurs courtes définie sont passés du type string au type enum pour une meilleure validation des données (par exemple, le champ Product.ProductAttributes.condition est désormais un enum).
• Suppression de la méthode de mise à jour des conditions de retour en ligne : la méthode onlineReturnPolicy.update est supprimée dans v1. Créez une politique de retour en ligne à l'aide de la méthode onlineReturnPolicy.create.

Comment procéder ?

La version v1beta de l'API Merchant doit être abandonnée le 28 février 2026. Pour en savoir plus sur le calendrier d'arrêt, consultez le guide de gestion des versions de l'API Merchant.

• La première étape de la migration consiste à vous enregistrer en tant que développeur (voir S'inscrire en tant que développeur). Vous devez appeler la méthode registerGcp pour chaque projet Google Cloud que vous utilisez pour l'authentification avant que les méthodes v1 ne fonctionnent.

• Quelle que soit la façon dont vous appelez les API (avec REST, gRPC ou en utilisant des bibliothèques clientes), vous pouvez migrer par étapes. Cela signifie que vous pouvez mettre à jour et migrer votre code une API à la fois (par exemple, en passant de l'API Products à l'API v1 tout en conservant l'API Accounts sur v1beta) sans avoir à mettre à jour l'intégralité de votre intégration en une seule fois.

Modifications détaillées des champs

Ce tableau fournit une comparaison détaillée des champs qui ont changé entre les versions v1beta et v1.

v1beta	v1	Description
Product.gtin	Product.gtins	Le champ des GTIN a été renommé.
Product.taxes	Supprimée	Le champ taxes a été supprimé.
Product.taxCategory	Supprimée	Le champ taxCategory a été supprimé.
Product.channel	Supprimée	Le champ channel a été supprimé. Utilisez le champ legacyLocal pour les cas d'utilisation locaux.
Product.attributes	Product.productAttributes	Le champ attributes a été renommé productAttributes.
availability, condition, gender, includedDestinations et excludedDestinations dans les champs Product sont représentés sous la forme strings (ou array de strings).	Ces champs sont désormais enums (ou array de enums).	Les champs avec une liste restreinte de valeurs définies sont passés du type string à enum.
price, salePrice, salePriceEffectiveDate et availability dans RegionalInventory	Déplacé vers RegionalInventory.regionalInventoryAttributes	Ces champs ont été déplacés sous regionalInventoryAttributes.
Le champ RegionalInventory.availability est un string	RegionalInventory.regionalInventoryAttributes.availability est désormais un enums	Le type de disponibilité est passé de string à enum.
price, salePrice, salePriceEffectiveDate, availability, quantity, pickupMethod, pickupSla et instoreProductLocation dans LocalInventory	Déplacé vers LocalInventory.localInventoryAttributes	Ces champs ont été déplacés sous localInventoryAttributes.
Le champ LocalInventory.availability est un string	LocalInventory.localInventoryAttributes.availability est désormais un enums	Le type de disponibilité est passé de string à enum.
LocalInventory.customAttributes	Supprimée	Les attributs personnalisés ne sont plus acceptés pour l'inventaire en magasin.
RegionalInventory.customAttributes	Supprimée	Les attributs personnalisés ne sont plus acceptés pour l'inventaire régional.
ProductInput.channel	Supprimée	Le champ channel a été supprimé. Utilisez le champ legacyLocal pour les cas d'utilisation locaux.
DataSource.channel	Supprimée	Le champ channel a été supprimé. Utilisez le champ legacyLocal pour les cas d'utilisation locaux.
Non disponible	ProductInput.legacyLocal	Nouveau champ booléen indiquant qu'un produit ne peut cibler que les méthodes marketing locales. L'ID de ressource produit sera précédé du préfixe "local~".
Non disponible	Product.legacyLocal	Un nouveau champ booléen permettant d'indiquer qu'un produit est vendu uniquement dans les magasins physiques et n'est pas disponible à l'achat en ligne.
Non disponible	DataSource.legacyLocal	Nouveau champ booléen indiquant qu'une source de données contient des produits vendus uniquement dans les magasins locaux.
OrderTrackingSignals.LineItemDetails.gtin	OrderTrackingSignals.LineItemDetails.gtins	Le champ gtin a été renommé gtins et est désormais un tableau de chaînes (au lieu d'une chaîne).
CreateAndConfigureAccountRequest.users	Supprimée	Le champ users a été supprimé. Utilisez le champ user pour ajouter l'administrateur initial au compte.