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:
- Wichtige Kontodetails (ID, Name, Einstellungen für Inhalte für Erwachsene) bleiben in der Ressource
Accounterhalten. - Informationen zum Unternehmen (Adresse, Telefonnummer, Kundenservice) werden jetzt über die Ressource
BusinessInfoverwaltet. - Website-URL und Anspruchserhebung werden von der Ressource
Homepageverarbeitet. - Die Nutzerverwaltung erfolgt über die Ressource
User. - Kontobeziehungen (Verknüpfungen mit erweiterten Konten, Drittanbietern und anderen Google-Diensten) werden über die Ressourcen
AccountRelationshipundAccountServiceverwaltet. - Attribute zur Unternehmensidentität (z. B. von Schwarzen Inhabern geführt, von Frauen geführt) werden über die Ressource
BusinessIdentityverwaltet. - Nutzungsbedingungen, ein neues Feature, werden von den Ressourcen
TermsOfServiceundTermsOfServiceAgreementStateverwaltet.
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
TermsOfServiceundTermsOfServiceAgreementStateprogrammatisch abrufen und akzeptieren. - Kontoerstellung: Die Methode
accounts.createAndConfigureunterstützt jetzt das Erstellen von Konten mit Beziehungen (z. B.accountManagement), das Festlegen eineraliasund das Unterdrücken der E‑Mail-Bestätigung mithilfe des Feldsuser.verificationMailSettings.verificationMailModezugunsten der API-basierten Bestätigung mit der neuen Methodeaccounts.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. |