Von v1beta zu v1 migrieren

In dieser Anleitung erfahren Sie, wie Sie von der Merchant API v1beta zur ersten Version für die allgemeine Verfügbarkeit, v1, migrieren. Die Version 1 enthält mehrere Updates und einige Änderungen, die möglicherweise Code-Updates erfordern. Diese Änderungen sollen die API vereinfachen und die Verwaltung Ihres Merchant Center-Kontos verbessern.

Wichtige Unterschiede

Hier sind die wichtigsten Änderungen, die Sie bei der Migration von v1beta zu v1 beachten müssen:

• Einmalige Registrierung von mindestens einem API-Entwickler für die Verwendung der Merchant API:Sie müssen die Methode registerGcp (nur einmal für jedes Google Cloud-Projekt, das für die Authentifizierung verwendet wird) aufrufen, um Ihre Kontaktdaten anzugeben. So können Sie die API verwenden und Updates und Ankündigungen zur Merchant API erhalten. Sie können keine v1- oder v1alpha-API verwenden, bis dieser Schritt abgeschlossen ist. Eine Anleitung finden Sie unter Als Entwickler registrieren.
• Product.attributes umbenannt: Das Feld Product.attributes wurde in Product.productAttributes umbenannt.
• Entfernung von Steuerinformationen auf Produktebene:Die Felder taxes und taxCategory wurden aus dem Objekt Product.productAttributes entfernt. Weitere Informationen finden Sie im Google Merchant Center-Hilfeartikel zum Thema Steuern.
• Änderungen am Feld „GTIN“:Das Feld gtin im Objekt Product.productAttributes wurde in gtins umbenannt, um besser widerzuspiegeln, dass es mehrere Werte enthalten kann. Das Feld gtin im Objekt OrderTrackingSignals.lineItemDetails ist jetzt ein array und wurde in gtins umbenannt.
• Entfernung des Channel-Felds:Das Feld channel wurde aus Produkten, Produkteingaben und Datenquellen entfernt. Ein neues boolesches Feld, legacyLocal, wurde eingeführt, um Produkte, die ausschließlich in physischen Geschäften verkauft werden, eindeutig zu kennzeichnen. Hinweis: Das Feld legacyLocal ist ein Hilfsfeld für die Migration und wird eingestellt, sobald Online- und lokale Marketingmethoden vollständig mit einer einzigen Produktquelle ausgerichtet werden können. Weitere Informationen finden Sie in der Tabelle im nächsten Abschnitt.
• Neue Felder für regionale und lokale Inventarattribute:
  • Alle RegionalInventory-Felder mit Ausnahme von name, account und region sind jetzt in einem neuen Objekt namens regionalInventoryAttributes enthalten. Das Attribut RegionalInventory.price befindet sich jetzt beispielsweise unter RegionalInventory.regionalInventoryAttributes.price.
  • Alle LocalInventory-Felder mit Ausnahme von name, account und storeCode sind jetzt in einem neuen Objekt namens localInventoryAttributes enthalten. Das Attribut LocalInventory.price befindet sich jetzt beispielsweise unter LocalInventory.localInventoryAttributes.price.
• Entfernung von customAttributes aus regionalen und lokalen Inventaren:Das Feld customAttributes wurde sowohl aus den Ressourcen RegionalInventory als auch aus LocalInventory entfernt.
• Optimierte Kontoerstellung:Das redundante Feld users wurde aus CreateAndConfigureAccountRequest entfernt. Verwenden Sie das Einzelfeld user, um einen ersten Nutzer mit einem neuen Konto zu verknüpfen.
• Bestimmte Attributtypen wurden von Strings in Enums geändert:Einige Felder in den Ressourcen Product und Inventory mit einer definierten kurzen Liste von Werten wurden zur besseren Datenvalidierung vom Typ string in den Typ enum geändert. Das Feld Product.ProductAttributes.condition ist jetzt beispielsweise ein enum.
• Entfernung der Methode zum Aktualisieren von Online-Rückgaberichtlinien:Die Methode onlineReturnPolicy.update wird in v1 entfernt. Erstellen Sie stattdessen eine Online-Rückgaberichtlinie mit der Methode onlineReturnPolicy.create.

Vorgehensweise

Die v1beta-Version der Merchant API wird am 28. Februar 2026 eingestellt. Weitere Informationen zum Zeitplan für die Einstellung finden Sie in der Anleitung zur Merchant API-Versionierung.

• Der erste Schritt bei der Migration ist die einmalige Entwicklerregistrierung (siehe Als Entwickler registrieren). Sie müssen die registerGcp-Methode für jedes Google Cloud-Projekt aufrufen, das Sie für die Authentifizierung verwenden, bevor v1-Methoden funktionieren.

• Unabhängig davon, wie Sie die APIs aufrufen (mit REST, gRPC oder über Clientbibliotheken), können Sie die Migration in Phasen durchführen. Das bedeutet, dass Sie Ihren Code API für API aktualisieren und migrieren können (z. B. die Products API zu v1 verschieben, während die Accounts API auf v1beta bleibt), ohne Ihre gesamte Integration auf einmal aktualisieren zu müssen.

Detaillierte Feldänderungen

Diese Tabelle enthält einen detaillierten Vergleich der Felder, die sich zwischen den Versionen v1beta und v1 geändert haben.

v1beta	v1	Beschreibung
Product.gtin	Product.gtins	Das Feld für GTINs wurde umbenannt.
Product.taxes	Entfernt	Das Feld „taxes“ wurde entfernt
Product.taxCategory	Entfernt	Das Feld „taxCategory“ wurde entfernt
Product.channel	Entfernt	Das Feld channel wurde entfernt. Verwenden Sie das Feld legacyLocal für lokale Anwendungsfälle.
Product.attributes	Product.productAttributes	Das Feld attributes wurde in productAttributes umbenannt.
availability, condition, gender, includedDestinations und excludedDestinations in Product-Feldern werden als strings (oder array von strings) dargestellt.	Diese Felder sind jetzt enums (oder array von enums).	Felder mit einer definierten kurzen Liste von Werten wurden vom Typ string in enum geändert.
price, salePrice, salePriceEffectiveDate und availability in RegionalInventory	Verschoben nach RegionalInventory.regionalInventoryAttributes	Diese Felder wurden in regionalInventoryAttributes verschoben.
Das Feld RegionalInventory.availability ist ein string	RegionalInventory.regionalInventoryAttributes.availability ist jetzt enums	Der Verfügbarkeitstyp wurde von string in enum geändert.
price, salePrice, salePriceEffectiveDate, availability, quantity, pickupMethod, pickupSla und instoreProductLocation in LocalInventory	Verschoben nach LocalInventory.localInventoryAttributes	Diese Felder wurden in localInventoryAttributes verschoben.
Das Feld LocalInventory.availability ist ein string	LocalInventory.localInventoryAttributes.availability ist jetzt enums	Der Verfügbarkeitstyp wurde von string in enum geändert.
LocalInventory.customAttributes	Entfernt	Benutzerdefinierte Attribute werden für lokales Inventar nicht mehr unterstützt.
RegionalInventory.customAttributes	Entfernt	Benutzerdefinierte Attribute werden für regionales Inventar nicht mehr unterstützt.
ProductInput.channel	Entfernt	Das Feld channel wurde entfernt. Verwenden Sie das Feld legacyLocal für lokale Anwendungsfälle.
DataSource.channel	Entfernt	Das Feld channel wurde entfernt. Verwenden Sie das Feld legacyLocal für lokale Anwendungsfälle.
Nicht verfügbar	ProductInput.legacyLocal	Ein neues boolesches Feld, das angibt, dass ein Produkt nur auf lokale Marketingmethoden ausgerichtet werden kann. Die Produktressourcen-ID hat das Präfix „local~“.
Nicht verfügbar	Product.legacyLocal	Ein neues boolesches Feld, das angibt, dass ein Produkt nur in lokalen Geschäften verkauft wird und nicht online gekauft werden kann.
Nicht verfügbar	DataSource.legacyLocal	Ein neues boolesches Feld, das angibt, ob eine Datenquelle Produkte enthält, die nur in Geschäften vor Ort verkauft werden.
OrderTrackingSignals.LineItemDetails.gtin	OrderTrackingSignals.LineItemDetails.gtins	Das Feld gtin wurde in gtins umbenannt und ist jetzt ein Array von Strings (anstatt eines Strings).
CreateAndConfigureAccountRequest.users	Entfernt	Das Feld users wurde entfernt. Verwenden Sie das Feld user, um den ersten Administrator für das Konto hinzuzufügen.