Wichtig: Die Content API for Shopping wird am 18. August 2026 eingestellt.

Wenn Sie mehr Zeit für die Migration zur Merchant API benötigen, können Sie eine Verlängerung des Zugriffs auf die Content API for Shopping beantragen.

Google verwendet KI-Technologie, um Inhalte in Ihre bevorzugte Sprache zu übersetzen. KI-Übersetzungen können Fehler enthalten.

Übersicht über den Dienst „Kundenabgleich für Treuepunkteprogramm“

In diesem Leitfaden wird beschrieben, wie Sie den Dienst zum Abgleich von Kundendaten aus Treuepunkten in der Merchant API verwenden. Mit diesem Dienst können Händler und Drittanbieter von Treuepunkten, die im Namen von Händlern handeln, Kundentreuepunktdaten wie Nutzer-IDs und Stufeninformationen für die organische Personalisierung in der Google Suche verwalten, ohne dass ein aktives Google Ads-Konto erforderlich ist.

Übersicht

Mit dem Kundenabgleich für Treuepunkteprogramme können Sie Treuepunktdaten hochladen, die dann verwendet werden, um organische Personalisierungsfunktionen für Treuepunkteprogramme in der Google Suche bereitzustellen, z. B. die Anzeige von mitgliedsspezifischen Preisen. Mit der benutzerdefinierten Methode ManageLoyaltyCustomerMatch können Sie Ihre Kunden mit Treuepunkteprogramm-Stufen verknüpfen und ihren Treuepunkteprogramm-Status anhand von Nutzer-IDs einfügen, aktualisieren oder entfernen.

Wichtige Konzepte

Einheitliche Schnittstelle:Ein eindeutiger Endpunkt zum Hinzufügen, Aktualisieren oder Entfernen von Details zur Kundenbindung.
Datenschutzorientiertes Design:Zum Schutz der Privatsphäre von Nutzern und zur Verhinderung unbefugter Kontoüberprüfungen werden in der API keine GET- oder LIST-Vorgänge unterstützt. So wird sichergestellt, dass Daten ohne Abruf oder Überprüfung verwaltet werden.
Flexible Identifizierung:Sie können Nutzer anhand von mindestens einer gültigen Kennung abgleichen, z. B. einer E-Mail-Adresse, Postanschrift oder Telefonnummer.
Verarbeitung auf Grundlage der Einwilligung:Der Dienst speichert und verwendet Kundendaten nur, wenn der Endnutzer die erforderliche Einwilligung für Google erteilt hat. Zum Schutz vor dem Abrufen von Konten oder des Einwilligungsstatus gibt der Dienst einen stillen Erfolg zurück, wenn keine Übereinstimmung gefunden wird oder keine Einwilligung erteilt wurde.

Vorbereitung

Beachten Sie die folgenden Anforderungen für die Nutzung des Kundenabgleichs für Treuepunkte:

Kontoeinrichtung:Sie benötigen ein aktives Merchant Center-Konto (oder autorisierten Zugriff auf das Konto des Händlers, wenn Sie ein Drittanbieter für Treuepunkte sind). Sie müssen kein Google Ads-Konto erstellen, um den Dienst zum Abgleich von Kunden mit Treuepunkten zu verwenden.
Konfiguration des Treuepunkteprogramms:Aktivieren Sie das Treuepunkteprogramm in Ihrem Merchant Center-Konto und sorgen Sie dafür, dass Sie Treuepunkteprogramm-Stufen definiert haben.
Reihenfolge der Stufen: Achten Sie auf die Reihenfolge, in der Ihre Treuepunkteprogramm-Stufen in der Merchant Center-Benutzeroberfläche definiert sind. Die API verwendet genau diese Reihenfolge für die Enum-Zuordnung.

Methode: `ManageLoyaltyCustomerMatch`

Die Methode ManageLoyaltyCustomerMatch dient als zentrale Schnittstelle für die Verwaltung von Kundenbindungskonten. Anhand der bereitgestellten Eingabe wird automatisch ermittelt, ob der Treuepunkte-Status eines Kunden eingefügt, aktualisiert oder entfernt werden soll. Der Vorgang ist idempotent: Wiederholte identische Anfragen haben dieselbe Wirkung wie eine einzelne Anfrage.

Die folgende Anfrage zeigt, wie Sie Kundenbindungskonten über die API verwalten:

POST https://merchantapi.googleapis.com/{API_VERSION}/accounts/{ACCOUNT_ID}/loyaltyCustomers:manage

In dieser Anfrage werden die folgenden erforderlichen Pfadparameter definiert:

API_VERSION: Die API-Version, z. B. v1.
ACCOUNT_ID: Die Merchant Center-Konto-ID.

Fügen Sie ein loyaltyCustomer-Objekt in den Anfragetext ein.

{
    "userIdentifier": {
      "emailAddress": "string",
      "address": {
        "addressLines": ["string"],
        "locality": "string",
        "administrativeArea": "string",
        "postalCode": "string",
        "regionCode": "string"
      },
      "phoneNumber": "string"
    },
    "loyaltyTier": "LoyaltyTier",
    "pointBalance": "integer"
  }

loyaltyCustomer-Felder

userIdentifier: Die Gruppe von Kennungen, die zum Abgleichen des Kunden verwendet werden. Mindestens ein Feld in „userIdentifier“ muss angegeben und gültig sein.
loyaltyTier: Die Treuestufe, die dem Kunden zugewiesen werden soll. Entspricht der Reihenfolge der Stufe bei der Einrichtung im Merchant Center. Weitere Informationen finden Sie unter loyaltyTier-Zuordnung. Verwenden Sie NON_MEMBER, um eine bestehende Verknüpfung zu entfernen.
pointBalance: Der aktuelle Punktestand des Kunden.

userIdentifier-Felder

Mindestens eines der folgenden Felder muss ausgefüllt sein:

emailAddress: Die E-Mail-Adresse des Kunden.
address: Die physische Adresse des Kunden. PostalCode ist erforderlich.
phoneNumber: Die Telefonnummer des Kunden. Das E.164-Format wird empfohlen.

`loyaltyTier`-Zuordnung verstehen

Die API verwendet die benutzerdefinierten Namen nicht. Die loyaltyTier-Enum-Werte (TIER1 bis TIER7) sind semantische Labels. Sie verwenden nicht die benutzerdefinierten Namen (z. B. „Gold Rewards“) oder benutzerdefinierten Labels (z. B. „gold_tier“), die Sie in der Merchant Center-Benutzeroberfläche zugewiesen haben. Stattdessen werden sie genau der Reihenfolge zugeordnet, in der Sie Ihre Stufen in den Einstellungen für das Treuepunkteprogramm im Merchant Center definiert haben:

TIER1: Entspricht der ersten Stufe, die in der Konfiguration Ihres Treuepunkteprogramms im Merchant Center aufgeführt ist.
TIER2: Entspricht der zweiten Stufe, die in der Konfiguration Ihres Treuepunkteprogramms im Merchant Center aufgeführt ist.
TIER3 bis TIER7: Entsprechen der dritten bis siebten Stufe, die in der Konfiguration Ihres Treuepunkteprogramms im Merchant Center aufgeführt sind.

Beispiel:

Wenn in Ihrem Merchant Center-Treuepunkteprogramm Stufen in dieser Reihenfolge definiert sind:

Stufenname: „Silver Status“, Stufenlabel: „silver“
Stufenname: „Gold Member“, Stufenlabel: „gold“
Stufenname: „Platinum Elite“, Stufenlabel: „platinum“

Gehen Sie dann bei accounts.loyaltyCustomers.manage-API-Aufrufen so vor:

Wenn Sie einem Kunden den Silver-Status zuweisen möchten, müssen Sie loyaltyTier: TIER1 verwenden.
Wenn Sie einem Kunden „Gold Member“ zuweisen möchten, müssen Sie loyaltyTier: TIER2 verwenden.
Wenn Sie einem Kunden „Platinum Elite“ zuweisen möchten, müssen Sie loyaltyTier: TIER3 verwenden.

Enum-Werte für LoyaltyTier

TIER1
TIER2
TIER3
TIER4
TIER5
TIER6
TIER7
NON_MEMBER (wird verwendet, um die Entfernung der Treuepunkteverknüpfung des Kunden zu signalisieren)

Antworttext von „ManageLoyaltyCustomerMatch“

Die Methode ManageLoyaltyCustomerMatch gibt ein ManageLoyaltyCustomerMatchResponse-Objekt zurück:

{
  "loyaltyCustomer": {
    // loyaltyCustomer object from the request
  }
}

Wichtige Hinweise zu Antworten

Erfolgreiches Upsert (Daten gespeichert): Damit die Treuepunktezuordnung eines Kunden erfolgreich gespeichert oder aktualisiert werden kann, müssen die folgenden Bedingungen erfüllt sein:
- Sie stimmen einen Google-Nutzer mit der angegebenen userIdentifier ab.
- Sie haben loyaltyTier in der Anfrage auf einen gültigen Wert festgelegt, der nicht NON_MEMBER ist.
- Der abgeglichene Nutzer hat der Datennutzung für Treuedaten zugestimmt.

Die Antwort enthält das loyaltyCustomer-Objekt aus Ihrer Anfrage. Das bedeutet, dass der Dienst die Daten erfolgreich verarbeitet und gespeichert hat:

{
  "loyaltyCustomer": {
    "userIdentifier": {
     "emailAddress": "customer@example.com"
    },
    "loyaltyTier": "TIER2",
    "pointBalance": 1500
    }
}

Erfolgreiches Löschen:Damit eine bestehende Treuepunkteverknüpfung für den Kunden mit diesem Händler erfolgreich entfernt werden kann, müssen die folgenden Bedingungen erfüllt sein:
- Sie stimmen einen Google-Nutzer mit der angegebenen userIdentifier ab.
- Sie haben loyaltyTier in der Anfrage auf NON_MEMBER festgelegt.

Die Antwort ist ein leeres JSON-Objekt:

{}

Keine Übereinstimmung / keine Einwilligung (stiller Erfolg): Wenn die angegebene userIdentifier nicht mit einem Google-Konto übereinstimmt oder der übereinstimmende Nutzer der Verwendung von Treuepunkteprogrammdaten nicht zugestimmt hat, gibt die API den Status HTTP 200 OK mit einem leeren JSON-Objekt zurück: {}. Das passiert sowohl bei Upsert- als auch bei Entfernungsversuchen.

Beispiele

TIER1 entspricht der ersten definierten Stufe (z. B. „Basic“) und TIER2 der zweiten Stufe (z. B. „Premium“).

Wenn Sie einen Kunden zu TIER2 hinzufügen oder seinen Status über eine E-Mail-Adresse aktualisieren möchten, senden Sie die folgende Anfrage:

POST
"https://merchantapi.googleapis.com/v1/accounts/{ACCOUNT_ID}/loyaltyCustomers:manage"
  -d '{
      "userIdentifier": {
        "emailAddress": "customer@example.com"
      },
      "loyaltyTier": "TIER2",
      "pointBalance": 1500
  }'

Wenn ein Nutzer erfolgreich abgeglichen wurde und seine Einwilligung erteilt hat, gibt die API die folgende Antwort zurück:

{
  "loyaltyCustomer": {
    "userIdentifier": {
      "emailAddress": "customer@example.com"
    },
    "loyaltyTier": "TIER2",
    "pointBalance": 1500
  }
}

Wenn es keine Übereinstimmung gibt oder der Nutzer nicht eingewilligt hat, gibt die API die folgende Antwort zurück:

{}

Wenn Sie die Treuepunktezuordnung eines Kunden über eine Telefonnummer entfernen möchten, senden Sie die folgende Anfrage:

POST
"https://merchantapi.googleapis.com/v1/accounts/{ACCOUNT_ID}/loyaltyCustomers:manage" \
  -d '{
      "userIdentifier": {
        "phoneNumber": "+18005550132"
      },
      "loyaltyTier": "NON_MEMBER"
  }'

Unabhängig davon, ob ein Datensatz vorhanden war, gibt die API die folgende Erfolgsantwort zurück:

{}

Wenn Sie einen Kunden mit mehreren Kennungen hinzufügen oder aktualisieren möchten, senden Sie die folgende Anfrage:

POST
"https://merchantapi.googleapis.com/v1/accounts/{ACCOUNT_ID}/loyaltyCustomers:manage" \
  -d '{
      "userIdentifier": {
        "emailAddress": "user@example.com",
        "address": {
          "postalCode": "94043",
          "regionCode": "US"
        }
      },
      "loyaltyTier": "TIER1"
  }'

Die Antwort ähnelt dem ersten Beispiel, je nach Übereinstimmung und Einwilligung.

Fehlerbehandlung

Die API verwendet Standard-HTTP-Codes. Häufige Fehlerstrings:

HTTP-Code	Fehlerstring	Beschreibung
400	INVALID_ARGUMENT	user_identifier oder loyalty_tier fehlt oder die Kennzeichnung ist leer.
401	UNAUTHENTICATED	Ungültige oder fehlende Anmeldedaten.
403	PERMISSION_DENIED	Der authentifizierte Nutzer hat keinen Zugriff auf das angegebene Merchant Center-Konto.
404	NOT_FOUND	Das angegebene Stufenlabel des Treuepunkteprogramms ist in Ihrer Konfiguration nicht vorhanden.
412	FAILED_PRECONDITION	Sie haben in Ihrem Konto kein Treuepunkteprogramm konfiguriert.
429	RESOURCE_EXHAUSTED	Kontingentlimit erreicht.