Migrer de v1beta à v1

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

Différences majeures

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 mises à jour et des annonces concernant l'API Merchant. Vous ne pourrez pas utiliser d'API v1 ni v1alpha tant que cette étape n'aura pas été effectuée. Pour en savoir plus sur le processus d'enregistrement, consultez la section Enregistrement.

• Encodage du nom du produit : les champs ProductInput.name et Product.name sont compatibles avec l'encodage base64url sans remplissage (section 5 de la norme RFC 4648). Suivez ces consignes :

  • Avant l'encodage, la chaîne doit respecter le format contentLanguage~feedLabel~offerId.

  • L'encodage est obligatoire si le nom de votre produit contient des caractères utilisés par l'API Merchant ou des caractères réservés aux URL, tels que :

    % . + / : ~ , ( * ! ) & ? = @ # $
    

  • Si le nom de votre produit respecte le contentLanguage~feedLabel~offerId format et ne contient pas de caractères utilisés par l'API Merchant ni de caractères réservés aux URL, vous pouvez utiliser le format brut, sans encodage.

  • Pour garantir une analyse cohérente et correcte, nous vous recommandons d'utiliser l'encodage base64url sans remplissage pour tous les noms de produits.

• Suppression des informations fiscales au niveau du produit : taxes et taxCategory.

• 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' Product.productAttributes objet. Pour en savoir plus, consultez l' article du Centre d'aide Google Merchant Center sur les taxes.

• Modifications apportées au champ GTIN : le gtin champ de l' Product.productAttributes objet a été renommé gtins pour mieux refléter le fait qu'il peut contenir plusieurs valeurs. Le champ gtin de l' OrderTrackingSignals.lineItemDetails objet est désormais un array et a également été renommé gtins.

• Suppression du champ "Channel" : le champ channel a été supprimé des produits, des entrées de produits 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 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 en magasin :

  • Tous les RegionalInventory champs, à 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 LocalInventory champs, à 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 en magasin : 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 utilisateur initial à un nouveau compte.

• Certains types d'attributs ont été modifiés et sont passés de chaînes à des énumérations : certains champs des ressources Product et Inventory avec une courte liste de valeurs définie sont passés du type string au type enum pour une meilleure validation des données (par exemple, le Product.ProductAttributes.condition champ est désormais une enum).

• Suppression de la méthode de mise à jour du règlement de retour en ligne : la onlineReturnPolicy.update méthode est supprimée dans v1. Créez plutôt un règlement de retour en ligne à l'aide de la méthode onlineReturnPolicy.create.

Comment procéder ?

La version v1beta de l'API Merchant sera mise hors service le 28 février 2026. Pour en savoir plus sur le calendrier de mise hors service, consultez le guide de gestion des versions de l'API Merchant.

• La première étape de la migration consiste à effectuer un enregistrement unique en tant que développeur (voir S'enregistrer en tant que développeur). Vous devez appeler la méthode registerGcp pour chaque projet Google Cloud que vous utilisez pour l'authentification avant qu'une méthode v1 ne fonctionne.

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

Modifications détaillées des champs

Ce tableau compare en détail les champs qui ont changé entre les versions v1beta et v1.

v1beta	v1	Description
ProductInput.name	ProductInput.name	Unpadded base64url encoding accepté et obligatoire pour les noms de produits contenant des caractères utilisés par l'API Merchant ou des caractères réservés aux URL.
Product.name	Product.name	Unpadded base64url encoding accepté et obligatoire pour les noms de produits contenant des caractères utilisés par l'API Merchant ou des caractères réservés aux URL.
Product.gtin	Product.gtins	Le champ des GTIN a été renommé.
Product.taxes	Supprimé	Le champ taxes a été supprimé.
Product.taxCategory	Supprimé	Le champ taxCategory a été supprimé.
Product.channel	Supprimé	Le champ channel a été supprimé. Utilisez le legacyLocal champ 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 forme de strings (ou de array de strings).	Ces champs sont désormais des enums (ou des array d'enums).	Les champs avec une courte liste de valeurs définie sont passés du type string au type 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 une string.	RegionalInventory.regionalInventoryAttributes.availability est désormais une 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 une string.	LocalInventory.localInventoryAttributes.availability est désormais une enums.	Le type de disponibilité est passé de string à enum.
LocalInventory.customAttributes	Supprimé	Les attributs personnalisés ne sont plus acceptés pour l'inventaire en magasin.
RegionalInventory.customAttributes	Supprimé	Les attributs personnalisés ne sont plus acceptés pour l'inventaire régional.
ProductInput.channel	Supprimé	Le champ channel a été supprimé. Utilisez le legacyLocal champ pour les cas d'utilisation locaux.
DataSource.channel	Supprimé	Le champ channel a été supprimé. Utilisez le legacyLocal champ pour les cas d'utilisation locaux.
Non disponible	ProductInput.legacyLocal	Nouveau champ booléen indiquant qu'un produit ne peut cibler que des méthodes marketing locales. L'ID de ressource du produit aura le préfixe "local~".
Non disponible	Product.legacyLocal	Nouveau champ booléen indiquant qu'un produit n'est vendu que dans des magasins locaux 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 des 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é	Le champ users a été supprimé. Utilisez le user champ pour ajouter l'administrateur initial au compte.