Kontoverwaltung migrieren

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

In dieser Anleitung werden die wichtigsten Änderungen erläutert und Sie erfahren, wie Sie Ihre bestehende Kontoverwaltungsintegration 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.

In der Merchant API wird dies in mehrere kleinere, fokussiertere Ressourcen aufgeteilt. 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 BusinessInfo-Ressource, anstatt das gesamte Account-Objekt zu aktualisieren.

Hier finden Sie eine Zusammenfassung der Zuordnung der Konzepte aus der Ressourcenübersicht der Content API for ShoppingAccount zu den neuen Ressourcen in der Merchant API:

• Wichtige Kontodetails (ID, Name, Einstellungen für Inhalte für Erwachsene) bleiben in der Account-Ressource.
• Informationen zum Unternehmen (Adresse, Telefonnummer, Kundenservice) werden jetzt über die BusinessInfo-Ressource verwaltet.
• Website-URL und Beanspruchung werden von der Ressource Homepage verarbeitet.
• Die Nutzerverwaltung wird über die User-Ressource abgewickelt.
• Kontobeziehungen (Links zu erweiterten Konten, Drittanbietern und anderen Google-Diensten) werden über die Ressourcen AccountRelationship und AccountService verwaltet.
• Attribute zur Unternehmensidentität (z. B. „Von Schwarzen Inhabern geführt“, „Von Frauen geführt“) werden über die Ressource BusinessIdentity verwaltet.
• Vereinbarungen zu den Nutzungsbedingungen sind eine neue Funktion, die über die Ressourcen TermsOfService und TermsOfServiceAgreementState verwaltet wird.

Neue Funktionen

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

• Nutzungsbedingungen:Nutzungsbedingungen programmatisch abrufen und akzeptieren mit den Ressourcen TermsOfService und TermsOfServiceAgreementState.
• Kontoerstellung: Mit der Methode accounts.createAndConfigure können jetzt Konten mit Beziehungen (z. B. accountManagement) erstellt, eine alias festgelegt und die E-Mail-Bestätigung mithilfe des Felds user.verificationMailSettings.verificationMailMode zugunsten der API-basierten Bestätigung mit der neuen Methode accounts.verifySelf unterdrückt werden.
• Kontozugriff über Alias: Sie können auf Konten im Format providerId~accountAlias zugreifen. So können Unternehmen, die mehrere Konten verwalten, ihre eigenen Konto-IDs verwenden.

Anfragen

In dieser Tabelle finden Sie einen zusammenfassenden Vergleich der Anfrage-URLs für häufige Aufgaben zur Kontoverwaltung 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}
Website beanspruchen	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 Account-Ressource in der Merchant API enthält die wichtigsten Details eines Merchant Center-Kontos, z. B. Name, ID und Grundeinstellungen.

Anfragevergleich

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} (Aktualisierung von Kernattributen)	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 reines Ausgabefeld. Die primäre Kennung ist die Ressource name.
name	account_name	Der für Menschen lesbare Name des Kontos.
language	language_code	Der Feldname ist jetzt language_code.

Informationen zum Unternehmen verwalten

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

Anfragevergleich

Beschreibung der Anfrage	Content API for Shopping	Merchant API
Unternehmensinformationen 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 ist jetzt phone und verwendet google.type.PhoneNumber.
customer_service.url	customer_service.uri	Der Feldname ist jetzt uri.

Startseite verwalten

Wenn Sie die Website-URL Ihres Geschäfts verwalten und die Bestätigung und Beanspruchung durchführen möchten, verwenden Sie die Homepage-Ressource. Dadurch werden das Feld websiteUrl und die Methode accounts.claimwebsite aus der Content API for Shopping ersetzt.

Anfragevergleich

Beschreibung der Anfrage	Content API for Shopping	Merchant API
Startseiten-URL abrufen	GET /content/v2.1/{merchantId}/accounts/{accountId} (Zugriff auf das Attribut website_url)	GET /accounts/v1/accounts/{account}/homepage
Startseiten-URL 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
Startseite nicht mehr beanspruchen	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 wird.

Nutzer verwalten

Mit der User-Ressource können Sie verwalten, wer auf ein Merchant Center-Konto zugreifen kann. Dadurch wird das users-Array in der Account-Ressource ersetzt. Ein wichtiger Unterschied ist der Prozess zur Erstellung von Nutzern. Wenn Sie in der Merchant API einen Nutzer hinzufügen, wird eine Einladung gesendet. Der Nutzer muss die Einladung annehmen, bevor er auf das Konto zugreifen kann.

Anfragevergleich

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 wiederkehrenden Enum-Feld zusammengefasst.
Nicht verfügbar	state	Ein neues Nur-Ausgabefeld, 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, für das ein Handshake-Prozess (Vorschlag und Annahme) erforderlich ist.

Anfragevergleich

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 erbrachten Dienstleistung (z.B. ACCOUNT_AGGREGATION).
status	handshake.approval_state (in AccountService)	Der Status des Links (z.B. PENDING, ESTABLISHED).

Steuereinstellungen für das Konto

Der accounttax-Dienst aus der Content API for Shopping ist in der Merchant API nicht verfügbar. Die Angabe der Umsatzsteuer für die USA ist nicht mehr erforderlich. Weitere Informationen finden Sie unter Aktualisierung der Merchant Center-Produktdatenspezifikation – 2025.

Unternehmensidentität verwalten

Mit der Ressource BusinessIdentity können Sie Attribute zu Ihrem Unternehmen selbst deklarieren. Dies ersetzt das businessIdentity-Objekt in der Content API for Shopping.

Anfragevergleich

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 einen Enum-Wert (SELF_IDENTIFIES_AS, DOES_NOT_SELF_IDENTIFY_AS) ersetzt, um die Deklaration expliziter zu gestalten. 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 ersetzt (PROMOTIONS_CONSENT_GIVEN, PROMOTIONS_CONSENT_DENIED).

Konten auflisten

In der Content API for Shopping war das einzige erweiterte Konto ein „Mehrfachkundenkonto (MCA)“ und es wurde eine accounts.list-Methode zum Auflisten der Konten des angegebenen Mehrfachkundenkontos bereitgestellt. Erweiterte Konten in der Merchant API sind viel leistungsfähiger und ermöglichen eine größere Bandbreite an Kontotypen und Beziehungen. Um eine unkomplizierte Migration für erweiterte Konten zu ermöglichen, bietet die Merchant API ein direktes Äquivalent zu accounts.list der Content API for Shopping als accounts.listSubaccounts-Methode. Wir führen eine neue, leistungsstärkere accounts.list-Methode ein, mit der sich Konten noch besser filtern lassen.

Anfragevergleich

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.