Kontoverwaltung migrieren

Die Accounts API ist in eine Sammlung von Ressourcen unterteilt, mit denen Sie Ihre Merchant Center-Konten effizienter verwalten und verschiedene Aspekte Ihres Kontos genauer steuern können.

In diesem Leitfaden werden die wichtigsten Änderungen erläutert und Sie erfahren, wie Sie Ihre bestehende Integration für die Kontoverwaltung von der Content API for Shopping zur Merchant API migrieren.

Von einer Ressource zu vielen

In der Content API for Shopping war die Ressource Account ein monolithisches Objekt, das alles vom Kontonamen und der Website-URL bis hin zu Nutzerlisten und Unternehmensinformationen enthielt.

Die Merchant API unterteilt diese in mehrere kleinere, fokussiertere Ressourcen. Diese Änderung ermöglicht gezieltere und effizientere API-Aufrufe. Wenn Sie beispielsweise nur Ihre Geschäftsadresse aktualisieren möchten, senden Sie jetzt eine PATCH-Anfrage an die Ressource BusinessInfo, anstatt das gesamte Account-Objekt zu aktualisieren.

Hier finden Sie eine Zusammenfassung, wie die Konzepte aus der Content API for Shopping-Ressource Account den neuen Ressourcen in der Merchant API zugeordnet werden:

Neue Funktionen

Die Merchant API bietet außerdem neue Funktionen für die Kontoverwaltung, die in der Content API for Shopping nicht verfügbar waren:

  • Nutzungsbedingungen: Nutzungsbedingungen mit den Ressourcen TermsOfService und TermsOfServiceAgreementState programmatisch abrufen und akzeptieren.
  • Kontoerstellung: Die Methode accounts.createAndConfigure unterstützt jetzt das Erstellen von Konten mit Beziehungen (z. B. accountManagement), das Festlegen einer alias und das Unterdrücken der E‑Mail-Bestätigung mithilfe des Felds user.verificationMailSettings.verificationMailMode zugunsten der API-basierten Bestätigung mit der neuen Methode accounts.verifySelf.
  • Kontozugriff über Alias: Zugriff auf Konten im Format providerId~accountAlias. So können Unternehmen, die mehrere Konten verwalten, ihre eigenen Kontokennungen verwenden.

Anfragen

Diese Tabelle enthält einen konsolidierten Vergleich der Anfrage-URLs für gängige Kontoverwaltungsaufgaben zwischen der Content API for Shopping und der Merchant API.

Beschreibung der Anfrage Content API for Shopping Merchant API
Konto abrufen GET https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/accounts/{accountId} GET https://merchantapi.googleapis.com/accounts/v1/accounts/{account}
Konto nach Alias abrufen Nicht direkt verfügbar GET https://merchantapi.googleapis.com/accounts/v1/accounts/{provider}~{alias}
Unterkonten auflisten GET https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/accounts GET https://merchantapi.googleapis.com/accounts/v1/accounts/{provider}:listSubaccounts
Unterkonto erstellen POST https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/accounts POST https://merchantapi.googleapis.com/accounts/v1/accounts:createAndConfigure
Kontodaten aktualisieren PUT https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/accounts/{accountId} PATCH für die entsprechende Ressource. So aktualisieren Sie beispielsweise den Kontonamen: PATCH https://merchantapi.googleapis.com/accounts/v1/accounts/{account}
Unterkonto löschen DELETE https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/accounts/{accountId} DELETE https://merchantapi.googleapis.com/accounts/v1/accounts/{account}
Anspruch auf Website erheben POST https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/accounts/{accountId}/claimwebsite POST https://merchantapi.googleapis.com/accounts/v1/accounts/{account}/homepage:claim
Konten verknüpfen POST https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/accounts/{accountId}/link POST https://merchantapi.googleapis.com/accounts/v1/accounts/{account}/services:propose

Wichtige Kontoinformationen verwalten

Die Ressource Account in der Merchant API enthält die wesentlichen Details eines Merchant Center-Kontos, z. B. Name, ID und grundlegende Einstellungen.

Vergleich anfordern

Beschreibung der Anfrage Content API for Shopping Merchant API
Kontodetails abrufen GET /content/v2.1/{merchantId}/accounts/{accountId} (Zugriff auf Kernattribute wie name, adult_content) GET /accounts/v1/accounts/{account}
Unterkonto erstellen POST /content/v2.1/{merchantId}/accounts POST /accounts/v1/accounts:createAndConfigure
Kontodetails aktualisieren PUT /content/v2.1/{merchantId}/accounts/{accountId} (Hauptattribute aktualisieren) PATCH /accounts/v1/accounts/{account}
Unterkonto löschen DELETE /content/v2.1/{merchantId}/accounts/{accountId} DELETE /accounts/v1/accounts/{account}

Detaillierter Feldvergleich

Content API for Shopping (Account) Merchant API (Account) Hinweise
id account_id Die numerische ID ist jetzt ein Nur-Ausgabe-Feld. Die primäre Kennung ist die Ressource name.
name account_name Der menschenlesbare Name des Kontos.
language language_code Der Feldname lautet jetzt language_code.

Informationen zu Ihrem Unternehmen verwalten

Mit der Ressource BusinessInfo können Sie öffentliche Informationen zu Ihrem Unternehmen verwalten, z. B. Ihre Adresse und Kontaktdaten für den Kundenservice. Dies ersetzt das businessInformation-Objekt in der Content API for Shopping.

Vergleich anfordern

Beschreibung der Anfrage Content API for Shopping Merchant API
Informationen zum Unternehmen abrufen GET /content/v2.1/{merchantId}/accounts/{accountId} (Zugriff auf das Attribut business_information) GET /accounts/v1/accounts/{account}/businessInfo
Informationen zum Unternehmen aktualisieren PUT /content/v2.1/{merchantId}/accounts/{accountId} (Aktualisierung des Attributs business_information) PATCH /accounts/v1/accounts/{account}/businessInfo

Detaillierter Feldvergleich

Content API for Shopping (business_information) Merchant API (BusinessInfo) Hinweise
phone_number phone Das Feld heißt jetzt phone und verwendet google.type.PhoneNumber.
customer_service.url customer_service.uri Der Feldname lautet jetzt uri.

Startseite verwalten

Mit der Ressource Homepage können Sie die Website-URL Ihres Geschäfts verwalten und die Bestätigung und Beanspruchung durchführen. Dies ersetzt das Feld websiteUrl und die Methode accounts.claimwebsite aus der Content API for Shopping.

Vergleich anfordern

Beschreibung der Anfrage Content API for Shopping Merchant API
URL der Startseite abrufen GET /content/v2.1/{merchantId}/accounts/{accountId} (Zugriff auf das Attribut website_url) GET /accounts/v1/accounts/{account}/homepage
URL der Startseite aktualisieren PUT /content/v2.1/{merchantId}/accounts/{accountId} (Aktualisierung des Attributs website_url) PATCH /accounts/v1/accounts/{account}/homepage
Startseite für Ansprüche POST /content/v2.1/{merchantId}/accounts/{accountId}/claimwebsite POST /accounts/v1/accounts/{account}/homepage:claim
Anspruch auf Startseite aufheben Nicht verfügbar POST /accounts/v1/accounts/{account}/homepage:unclaim

Detaillierter Feldvergleich

Content API for Shopping (Account) Merchant API (Homepage) Hinweise
website_url uri Die URL der Startseite des Geschäfts.
Nicht direkt verfügbar claimed Ein boolesches Feld, das true ist, wenn die Startseite beansprucht wurde.

Nutzer verwalten

Mit der Ressource User können Sie festlegen, wer auf ein Merchant Center-Konto zugreifen darf. Dadurch wird das Array users in der Ressource Account ersetzt. Ein wesentlicher Unterschied ist der Prozess der Nutzererstellung. In der Merchant API wird beim Hinzufügen eines Nutzers eine Einladung gesendet. Der Nutzer muss die Einladung annehmen, bevor er auf das Konto zugreifen kann.

Vergleich anfordern

Beschreibung der Anfrage Content API for Shopping Merchant API
Nutzer auflisten GET /content/v2.1/{merchantId}/accounts/{accountId} (Zugriff auf das Attribut users) GET /accounts/v1/accounts/{account}/users
Nutzer erstellen PUT /content/v2.1/{merchantId}/accounts/{accountId} (Aktualisierung des Attributs users) POST /accounts/v1/accounts/{account}/users
Nutzer aktualisieren PUT /content/v2.1/{merchantId}/accounts/{accountId} (Aktualisierung des Attributs users) PATCH /accounts/v1/accounts/{account}/users/{email}
Nutzer löschen PUT /content/v2.1/{merchantId}/accounts/{accountId} (Aktualisierung des Attributs users) DELETE /accounts/v1/accounts/{account}/users/{email}

Detaillierter Feldvergleich

Content API for Shopping (users-Array-Objekt) Merchant API (User-Ressource) Hinweise
email_address name (im Format accounts/{account}/users/{email}) Die E-Mail-Adresse des Nutzers ist jetzt Teil des Ressourcennamens.
admin, order_manager, reporting_manager usw. access_rights Zugriffsrechte werden jetzt in einem wiederholten Enum-Feld zusammengefasst.
Nicht verfügbar state Ein neues Nur-Ausgabe-Feld, das angibt, ob der Nutzer PENDING oder VERIFIED ist.

Kontobeziehungen und Dienste verwalten

In der Content API for Shopping wurden Beziehungen mit accounts.link verwaltet. Die Merchant API führt ein expliziteres Modell mit den Ressourcen AccountService und AccountRelationship ein, das einen Handshake-Prozess (Vorschlagen und Akzeptieren) erfordert.

Vergleich anfordern

Beschreibung der Anfrage Content API for Shopping Merchant API
Konten verknüpfen POST /content/v2.1/{merchantId}/accounts/{accountId}/link POST /accounts/v1/accounts/{account}/services:propose
Verknüpfte Konten auflisten GET /content/v2.1/{merchantId}/accounts/{accountId}/listlinks GET /accounts/v1/accounts/{account}/relationships und GET /accounts/v1/accounts/{account}/services

Detaillierter Feldvergleich

Content API for Shopping (AccountLink) Merchant API (AccountService, AccountRelationship) Hinweise
linked_account_id provider (in AccountService) Die ID des Kontos, das den Dienst bereitstellt.
service service_type (in AccountService) Die Art der angebotenen Dienstleistung (z.B. ACCOUNT_AGGREGATION).
status handshake.approval_state (in AccountService) Der Status der Verknüpfung (z.B. PENDING, ESTABLISHED).

Steuereinstellungen für das Konto

Der Dienst accounttax der Content API for Shopping ist in der Merchant API nicht verfügbar. Die Angabe der US-Verkaufssteuer ist nicht mehr erforderlich. Weitere Informationen finden Sie unter Aktualisierung der Merchant Center-Produktdatenspezifikation – 2025.

Unternehmensidentität verwalten

Verwenden Sie die Ressource BusinessIdentity, um Attribute zu Ihrem Unternehmen selbst anzugeben. Dies ersetzt das Objekt businessIdentity in der Content API for Shopping.

Vergleich anfordern

Beschreibung der Anfrage Content API for Shopping Merchant API
Unternehmensidentität abrufen GET /content/v2.1/{merchantId}/accounts/{accountId} (Zugriff auf das Attribut business_identity) GET /accounts/v1/accounts/{account}/businessIdentity
Unternehmensidentität aktualisieren PUT /content/v2.1/{merchantId}/accounts/{accountId} (Aktualisierung des Attributs business_identity) PATCH /accounts/v1/accounts/{account}/businessIdentity

Detaillierter Feldvergleich

Content API for Shopping (business_identity) Merchant API (BusinessIdentity) Hinweise
black_owned.self_identified (boolesch) black_owned.identity_declaration (Aufzählung) Der boolesche Wert wird durch ein Enum (SELF_IDENTIFIES_AS, DOES_NOT_SELF_IDENTIFY_AS) ersetzt, um eine explizitere Deklaration zu ermöglichen. Dies gilt für alle Identitätsattribute.
include_for_promotions (boolesch) promotions_consent (Aufzählung) Ein globaler boolescher Wert wird durch ein aussagekräftigeres Enum (PROMOTIONS_CONSENT_GIVEN, PROMOTIONS_CONSENT_DENIED) ersetzt.

Konten auflisten

In der Content API for Shopping war der einzige Typ eines erweiterten Kontos ein „Mehrfachkundenkonto“ (Multi-Client Account, MCA). Es wurde eine accounts.list-Methode bereitgestellt, um die Konten des jeweiligen Mehrfachkundenkontos aufzulisten. Erweiterte Konten in der Merchant API sind viel leistungsfähiger und ermöglichen eine größere Auswahl an Kontotypen und Beziehungen. Um eine unkomplizierte Migration für erweiterte Konten zu ermöglichen, bietet die Merchant API ein direktes Äquivalent zur accounts.list der Content API for Shopping als accounts.listSubaccounts-Methode. Wir führen eine neue, leistungsstärkere accounts.list-Methode ein, die eine erweiterte Kontofilterung ermöglicht.

Vergleich anfordern

Beschreibung der Anfrage Content API for Shopping Merchant API
Konten eines erweiterten Kontos auflisten GET /content/v2.1/{merchantId}/accounts GET /accounts/v1/accounts/{providerId}:listSubaccounts
Alle zugänglichen Konten auflisten Nicht verfügbar GET /accounts/v1/accounts

Detaillierter Feldvergleich (Anfrageparameter)

Content API for Shopping (accounts.list) Merchant API (accounts.listSubaccounts) Hinweise
merchant_id (Pfadparameter) provider (Pfadparameter) Die ID des erweiterten Kontos im Format accounts/{account}.
max_results page_size Die maximale Anzahl der zurückzugebenden Konten.