Die Merchant API v1beta wurde am 28. Februar 2026 eingestellt. Eine Anleitung zur Umstellung auf die aktuelle stabile Version finden Sie unter Von v1beta zu v1 migrieren.

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 dieser Anleitung wird beschrieben, wie Sie den Dienst für den Kundenabgleich für Treuepunkteprogramme in der Merchant API verwenden. Mit diesem Dienst können Händler Kundentreuedaten wie Nutzerkennungen und Stufeninformationen für die organische Personalisierung in der Google Suche verwalten, ohne dass ein aktives Google Ads-Konto erforderlich ist.

Übersicht

Mit dem Dienst für den Kundenabgleich für Treuepunkteprogramme können Sie Treuedaten hochladen, die dann verwendet werden, um organische Personalisierungsfunktionen für Treuepunkteprogramme in der Google Suche bereitzustellen, z. B. die Anzeige von mitgliederspezifischen Preisen. Mit der ManageLoyaltyCustomerMatch benutzerdefinierten Methode können Sie Ihre Kunden mit Stufen von Treuepunkteprogrammen verknüpfen. So können Sie den Treuestatus anhand von Nutzer kennungen einfügen, aktualisieren oder entfernen.

Wichtige Konzepte

Einheitliche Benutzeroberfläche: Ein eindeutiger Endpunkt zum Hinzufügen, Aktualisieren oder Entfernen von Details zu Kundentreuestufen.
Datenschutzorientiertes Design: Zum Schutz der Privatsphäre von Nutzern und zur Verhinderung unbefugter Kontoabfragen werden von der API keine GET- oder LIST-Vorgänge unterstützt. So wird sichergestellt, dass Daten ohne Abruf oder Überprüfung verwaltet werden.
Flexible Identifizierung: Nutzer können mit mindestens einer gültigen Kennung abgeglichen werden, z. B. einer E‑Mail-Adresse, einer Postanschrift oder einer Telefonnummer.
Einwilligungsbasierte Verarbeitung: Der Dienst speichert und verwendet Kundendaten nur wenn der Endnutzer Google die erforderliche Einwilligung erteilt hat. Zum Schutz vor Abfragen des Kontostatus oder des Einwilligungsstatus gibt der Dienst bei fehlender Übereinstimmung oder fehlender Einwilligung eine stumme Erfolgsmeldung zurück.

Vorbereitung

Folgende Voraussetzungen müssen erfüllt sein, um den Dienst für den Kundenabgleich für Treuepunkteprogramme verwenden zu können:

Kontoeinrichtung:Sie benötigen ein aktives Merchant Center-Konto. Sie müssen kein Google Ads-Konto erstellen, um den Dienst für den Kundenabgleich für Treuepunkteprogramme verwenden zu können.
Konfiguration des Treuepunkteprogramms: Aktivieren Sie das Treuepunkteprogramm in Ihrem Merchant Center-Konto und legen Sie Treuestufen fest.
Reihenfolge der Stufen:Achten Sie auf die Reihenfolge, in der Ihre Treuestufen in der Merchant Center-Benutzeroberfläche definiert sind. Die API verwendet genau diese Reihenfolge für die Zuordnung von Aufzählungen.

Methode: `ManageLoyaltyCustomerMatch`

Die Methode ManageLoyaltyCustomerMatch dient als zentrale Schnittstelle für die Verwaltung von Verknüpfungen für Kundentreue. Anhand der eingegebenen Daten ermittelt der Dienst automatisch, ob der Treuestufenstatus 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 Verknüpfungen für Kundentreue ü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 im Anfragetext ein loyaltyCustomer-Objekt 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 Kennungen, die zum Abgleich des Kunden verwendet werden. Mindestens ein Feld in „userIdentifier“ muss angegeben und gültig sein.
loyaltyTier: Die Treuestufe, die mit dem Kunden verknüpft werden soll. Entspricht der Reihenfolge der Stufe in der Merchant Center-Einrichtung. Weitere Informationen finden Sie unter Zuordnung loyaltyTier. Verwenden Sie NON_MEMBER , um eine vorhandene Verknüpfung zu entfernen.
pointBalance: Der aktuelle Punktestand des Kunden.

userIdentifier-Felder

Es muss mindestens eines der folgenden Felder verfügbar sein:

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

Zuordnung von `loyaltyTier`

Die API verwendet nicht die benutzerdefinierten Namen. Die Aufzählungswerte von loyaltyTier (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 des Treuepunkteprogramms im Merchant Center aufgeführt ist.
TIER2: Entspricht der zweiten Stufe, die in der Konfiguration des Treuepunkteprogramms im Merchant Center aufgeführt ist.
TIER3 bis TIER7: Entsprechen der dritten bis siebten Stufe , die in der Konfiguration des Treuepunkteprogramms im Merchant Center aufgeführt sind.

Beispiel :

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

Stufenname: „Silberstatus“, Stufenlabel: „silber“
Stufenname: „Gold-Mitglied“, Stufenlabel: „gold“
Stufenname: „Platinum Elite“, Stufenlabel: „platinum“

Dann in accounts.loyaltyCustomers.manage -API-Aufrufen:

Um einen Kunden der Stufe „Silberstatus“ zuzuweisen, müssen Sie loyaltyTier: TIER1 verwenden.
Um einen Kunden der Stufe „Gold-Mitglied“ zuzuweisen, müssen Sie loyaltyTier: TIER2 verwenden.
Um einen Kunden der Stufe „Platinum Elite“ zuzuweisen, müssen Sie loyaltyTier: TIER3 verwenden.

Aufzählungswerte für LoyaltyTier

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

Antworttext von ManageLoyaltyCustomerMatch

Die ManageLoyaltyCustomerMatch Methode gibt ein ManageLoyaltyCustomerMatchResponse Objekt zurück:

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

Wichtige Hinweise zu möglichen Antworten:

Erfolgreiches Upsert (Daten gespeichert) : Damit die Treuestufenverknüpfung eines Kunden erfolgreich gespeichert oder aktualisiert werden kann, müssen die folgenden Bedingungen erfüllt sein:
- Sie gleichen einen Google-Nutzer mit der angegebenen userIdentifier ab.
- Sie legen loyaltyTier in der Anfrage auf einen gültigen Wert fest, 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 die Daten erfolgreich verarbeitet und gespeichert wurden:

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

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

Die Antwort ist ein leeres JSON-Objekt:

{}

Keine Übereinstimmung / keine Einwilligung (stumme Erfolgsmeldung) : Wenn die angegebene userIdentifier nicht mit einem Google-Konto übereinstimmt oder der abgeglichene Nutzer der Verwendung von Treuedaten nicht zugestimmt hat, gibt die API den Status HTTP 200 OK mit einem leeren JSON-Objekt zurück: {}. Das gilt sowohl für Upsert- als auch für Entfernungs versuche.

Beispiele

TIER1 entspricht der ersten definierten Stufe des Händlers, „Basic“, und TIER2 der zweiten Stufe, „Premium“

Wenn Sie einen Kunden zu TIER2 hinzufügen oder seinen Status mit einer 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 keine Übereinstimmung vorliegt oder der Nutzer keine Einwilligung erteilt hat, gibt die API die folgende Antwort zurück:

{}

Wenn Sie die Treueverknüpfung eines Kunden mit einer 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 Erfolgsmeldung 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 sind:

HTTP-Code	Fehlerstring	Beschreibung
400	INVALID_ARGUMENT	user_identifier oder loyalty_tier fehlt oder die Kennung 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 für die Treuestufe ist in Ihrer Konfiguration nicht vorhanden.
412	FAILED_PRECONDITION	Sie haben in Ihrem Konto kein Treuepunkteprogramm konfiguriert.
429	RESOURCE_EXHAUSTED	Kontingentlimit erreicht.