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

In diesem Leitfaden wird beschrieben, wie Sie den Loyalty Customer Match Service in der Merchant API verwenden. Mit diesem Dienst können Händler und Drittanbieter von Treueprogrammen, die im Auftrag von Händlern handeln, Daten zum Kundenbindungsprogramm wie Nutzer-IDs und Informationen zu Stufen für die organische Personalisierung in der Google Suche verwalten, ohne dass ein aktives Google Ads-Konto erforderlich ist.

Übersicht

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

Wichtige Konzepte

  • Einheitliche Oberfläche: Ein eindeutiger Endpunkt zum Hinzufügen, Aktualisieren oder Entfernen von Details zur Treuestufe von Kunden.
  • Datenschutzorientiertes Design: Zum Schutz der Privatsphäre der Nutzer und zur Verhinderung unbefugter Kontoabfragen unterstützt die API keine GET- oder LIST-Vorgänge. So wird sichergestellt, dass Daten ohne Abruf oder Prüfung verwaltet werden.
  • Flexible Identifizierung: Nutzer können anhand mindestens einer gültigen Kennung wie einer E-Mail-Adresse, einer Postanschrift oder einer Telefonnummer abgeglichen werden.
  • Einwilligungsbasierte Verarbeitung: Der Dienst speichert und verwendet Kundendaten nur, wenn der Endnutzer Google die erforderliche Einwilligung erteilt hat. Zum Schutz und zur Verhinderung von Abfragen zur Existenz von Konten oder zum Einwilligungsstatus gibt der Dienst eine Erfolgsmeldung zurück, wenn keine Übereinstimmung gefunden wird oder keine Einwilligung erteilt wurde.

Vorbereitung

Für die Nutzung des Kundenabgleichs für Treuepunkteprogramme gelten die folgenden Anforderungen:

  • Kontoeinrichtung: Sie benötigen ein aktives Merchant Center-Konto (oder autorisierten Zugriff auf das Konto des Händlers, wenn Sie ein Drittanbieter für Treuepunkteprogramme sind). Sie müssen kein Google Ads-Konto erstellen, um den Dienst für den Kundenabgleich für Treuepunkteprogramme zu verwenden.
  • Konfiguration des Treuepunkteprogramms: Aktiviert das Treuepunkteprogramm in eurem Merchant Center-Konto und legt 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 Sequenz für die Enum-Zuordnung.

Methode: ManageLoyaltyCustomerMatch

Die Methode ManageLoyaltyCustomerMatch dient als zentrale Schnittstelle für die Verwaltung von Kundenbindungsverknüpfungen. Basierend auf der bereitgestellten Eingabe bestimmt 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 Kundenbindungsprogramme ü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 Kennungen, die für den Abgleich des Kunden verwendet werden. Mindestens ein Feld in „userIdentifier“ muss angegeben und gültig sein.
  • loyaltyTier: Die Treuestufe, die dem Kunden zugeordnet werden soll. Entspricht der Reihenfolge der Stufe in der Merchant Center-Einrichtung. Weitere Informationen finden Sie unter loyaltyTier-Zuordnung. Verwenden Sie NON_MEMBER, um eine vorhandene Verknüpfung zu entfernen.
  • pointBalance: Der aktuelle Punktestand des Kunden.

userIdentifier-Felder

Geben Sie mindestens eines der folgenden Felder an:

  • 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. Die benutzerdefinierten Namen (z. B. „Gold Rewards“) oder benutzerdefinierten Labels (z. B. „gold_tier“), die Sie in der Merchant Center-Benutzeroberfläche zugewiesen haben, werden nicht verwendet. Stattdessen entsprechen sie genau der Reihenfolge, in der Sie Ihre Stufen in den Einstellungen des Treuepunkteprogramms 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 für Ihr Treuepunkteprogramm im Merchant Center Stufen in dieser Reihenfolge definiert sind:

  1. Stufenname: „Silberstatus“, Stufenlabel: „silber“
  2. Stufenname: Gold Member, Stufenlabel: gold
  3. Stufenname: „Platinum Elite“, Stufenlabel: „platinum“

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

  • Wenn Sie einem Kunden den Silberstatus zuweisen möchten, müssen Sie loyaltyTier: TIER1 verwenden.
  • Wenn Sie einen Kunden der Gruppe Gold Member zuweisen möchten, müssen Sie loyaltyTier: TIER2 verwenden.
  • Wenn Sie einen Kunden Platinum Elite zuweisen möchten, müssen Sie loyaltyTier: TIER3 verwenden.

LoyaltyTier-Enum-Werte

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

Antworttext von „ManageLoyaltyCustomerMatch“ verstehen

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

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

Wichtige Hinweise zu Antworten

  • Erfolgreicher Upsert (Daten gespeichert): Damit die Zuordnung der Treuestufe eines Kunden erfolgreich gespeichert oder aktualisiert werden kann, müssen die folgenden Bedingungen erfüllt sein:

    • Sie einen Google-Nutzer mit der angegebenen userIdentifier abgleichen
    • Sie legen loyaltyTier in der Anfrage auf einen gültigen Wert außer NON_MEMBER fest.
    • der übereinstimmende Nutzer der Verwendung von Treuedaten zugestimmt hat

Die Antwort enthält das Objekt loyaltyCustomer 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 Treueverknüpfung für den Kunden mit diesem Händler entfernt werden kann, müssen die folgenden Bedingungen erfüllt sein:
    • Sie einen Google-Nutzer mit der angegebenen userIdentifier abgleichen
    • Sie legen loyaltyTier in der Anfrage auf NON_MEMBER fest.

Die Antwort ist ein leeres JSON-Objekt:

{}
  • Keine Übereinstimmung / keine Einwilligung (stiller Erfolg): Wenn die angegebene userIdentifier keinem Google-Konto entspricht oder der übereinstimmende Nutzer der Verwendung von Daten zum Kundenbindungsprogramm nicht zugestimmt hat, gibt die API den Status HTTP 200 OK mit einem leeren JSON-Objekt zurück: {}. Dies gilt sowohl für Upsert- als auch für Entfernungsversuche.

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 mithilfe 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 es keine Übereinstimmung gibt oder der Nutzer nicht zugestimmt hat, gibt die API die folgende Antwort zurück:

{}

Senden Sie die folgende Anfrage, um die Treueverknüpfung eines Kunden mithilfe einer Telefonnummer zu entfernen:

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

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

{}

Senden Sie die folgende Anfrage, um einen Kunden mit mehreren Kennungen hinzuzufügen oder zu aktualisieren:

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 Error String 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 des Treuepunkteprogramms ist in Ihrer Konfiguration nicht vorhanden.
412 FAILED_PRECONDITION Sie haben in Ihrem Konto kein Treuepunkteprogramm konfiguriert.
429 RESOURCE_EXHAUSTED Kontingentlimit erreicht.

Beispiele für Fehler

Beispiel für 404 NOT_FOUND:

Eine gültige Anfrage an eine Konto-ID, für die kein Treuepunkteprogramm konfiguriert ist.

Die API gibt die folgende Fehlerantwort zurück:

{
  "error": {
    "code": 404,
    "message": "The loyalty program is not found for account: {ACCOUNT_ID}.",
    "status": "NOT_FOUND",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "notFound",
        "domain": "merchantapi.googleapis.com",
        "metadata": {
          "ACCOUNT_ID": "{ACCOUNT_ID}",
          "REASON": "NOT_FOUND_LOYALTY_PROGRAM"
        }
      }
    ]
  }
}

Grund: Das Händlerkonto im Pfad hat kein aktives Treuepunkteprogramm.

Beispiele für 400 INVALID_ARGUMENT:

Ein Fehler tritt auf, wenn die Anfrage einen ungültigen Wert für das Feld loyaltyTier enthält:

{
  "loyaltyCustomer": {
    "userIdentifier": {
      "emailAddress": "customer@example.com"
    },
    "loyaltyTier": "TIER11",
    "pointBalance": 100
  }
}

Die API gibt die folgende Fehlerantwort zurück:

{
  "error": {
    "code": 400,
    "message": "Invalid value at 'loyalty_customer.loyalty_tier' (type.googleapis.com/google.shopping.merchant.loyaltycustomers.v1.LoyaltyCustomer.LoyaltyTier), \"TIER11\"",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.BadRequest",
        "fieldViolations": [
          {
            "field": "loyalty_customer.loyalty_tier",
            "description": "Invalid value at 'loyalty_customer.loyalty_tier' (type.googleapis.com/google.shopping.merchant.loyaltycustomers.v1.LoyaltyCustomer.LoyaltyTier), \"TIER11\""
          }
        ]
      }
    ]
  }
}

Grund: TIER11 ist kein gültiger Enum-Wert für loyaltyTier. Derselbe Fehler kann auftreten, wenn Sie versuchen, TIER2 anzugeben, obwohl nur eine Stufe verfügbar ist.

Ein Fehler tritt auf, wenn das erforderliche Feld loyaltyTier im Anfragetext fehlt:

{
  "loyaltyCustomer": {
    "userIdentifier": {
      "emailAddress": "customer@example.com"
    },
    "pointBalance": 100
  }
}

Die API gibt die folgende Fehlerantwort zurück:

{
  "error": {
    "code": 400,
    "message": "[loyalty_customer.loyalty_tier] Required field not provided: loyalty_customer.loyalty_tier",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "required",
        "domain": "merchantapi.googleapis.com",
        "metadata": {
          "FIELD_LOCATION": "loyalty_customer.loyalty_tier",
          "REASON": "MISSING_REQUIRED_FIELD"
        }
      }
    ]
  }
}

Grund: Das Feld loyaltyTier ist erforderlich.

Ein Fehler tritt auf, wenn eine Adresskennung unvollständig ist, z. B. wenn das Feld „postalCode“ fehlt:

{
  "loyaltyCustomer": {
    "userIdentifier": {
      "address": {
        "locality": "Sunnyvale",
        "administrativeArea": "CA",
        "regionCode": "US"
      }
    },
    "loyaltyTier": "TIER1",
    "pointBalance": 100
  }
}

Die API gibt die folgende Fehlerantwort zurück:

{
  "error": {
    "code": 400,
    "message": "[loyalty_customer.user_identifier] The format of loyalty_customer.user_identifier does not match the expected format ... Value: at least one valid user identifier should be provided.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "invalid",
        "domain": "merchantapi.googleapis.com",
        "metadata": {
          "FIELD_NAME": "loyalty_customer.user_identifier",
          "REASON": "INVALID_VALUE"
        }
      }
    ]
  }
}

Grund: Es wurde eine Adresse angegeben, aber das erforderliche Feld postalCode fehlt. Daher wird sie nicht als gültige Kennzeichnung betrachtet.

Ein Fehler tritt auf, wenn Sie einen Stufenindex anfordern, der außerhalb der Grenzen des konfigurierten Programms liegt:

Szenario: Der Händler hat im Merchant Center nur eine Stufe konfiguriert.

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

Die API gibt die folgende Fehlerantwort zurück:

{
  "error": {
    "code": 400,
    "message": "[loyalty_customer.loyalty_tier] The format of loyalty_customer.loyalty_tier does not match the expected format `valid LoyaltyTier`. Value: TIER2.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "invalid",
        "domain": "merchantapi.googleapis.com",
        "metadata": {
          "FIELD_NAME": "loyalty_customer.loyalty_tier",
          "PATTERN": "valid LoyaltyTier",
          "FIELD_VALUE": "TIER2",
          "REASON": "INVALID_VALUE"
        }
      }
    ]
  }
}

Grund: TIER2 wird angefordert, aber für das mit dem Konto verknüpfte Treuepunkteprogramm ist keine zweite Stufe definiert.

Ein Fehler tritt auf, wenn die Anfrage einen fehlerhaften emailAddress enthält:

{
  "loyaltyCustomer": {
    "userIdentifier": {
      "emailAddress": "customer@google"
    },
    "loyaltyTier": "TIER1",
    "pointBalance": 100
  }
}

Die API gibt die folgende Fehlerantwort zurück:

{
  "error": {
    "code": 400,
    "message": "[loyalty_customer.user_identifier] The format of loyalty_customer.user_identifier does not match the expected format `email_address: \t \"customer@google\"\n`. Value: at least one valid user identifier should be provided.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "invalid",
        "domain": "merchantapi.googleapis.com",
        "metadata": {
          "FIELD_NAME": "loyalty_customer.user_identifier",
          "REASON": "INVALID_VALUE"
        }
      }
    ]
  }
}

Grund: Das Format der E-Mail-Adresse ist ungültig.

Wenn das userIdentifier-Objekt leer ist, tritt ein Fehler auf:

{
  "loyaltyCustomer": {
    "userIdentifier": {},
    "loyaltyTier": "TIER1",
    "pointBalance": 100
  }
}

Die API gibt die folgende Fehlerantwort zurück:

{
  "error": {
    "code": 400,
    "message": "[loyalty_customer.user_identifier] Required field not provided: loyalty_customer.user_identifier",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "required",
        "domain": "merchantapi.googleapis.com",
        "metadata": {
          "FIELD_LOCATION": "loyalty_customer.user_identifier",
          "REASON": "MISSING_REQUIRED_FIELD"
        }
      }
    ]
  }
}

Ursache: Das Objekt userIdentifier ist vorhanden, enthält aber keine tatsächlichen Kennzeichnungsfelder.

Hinweis: Kennungsvalidierung:

  • Die API führt grundlegende Formatprüfungen für Kennungen durch (z. B. E-Mail-Struktur, Vorhandensein von postalCode in Adressen).
  • Einige Kennungen, die die ersten Prüfungen bestehen, stimmen jedoch möglicherweise mit keinem Google-Nutzerkonto überein oder haben ein Format, das vom Backend-Abgleichsystem nicht erkannt wird. In solchen Fällen erhalten Sie die leere Antwort {} mit dem HTTP-Status 200 OK.

Best Practices

Folgen Sie diesen Best Practices, um Ihre Integration zu optimieren.

  • Für die Integration im großen Maßstab: Da die API auf Anfragebasis arbeitet, ist clientseitige Parallelität erforderlich, um den erforderlichen Durchsatz für große Datasets zu erreichen. Sie sollten Ihre Integration so gestalten, dass mehrere gleichzeitige Anfragen verarbeitet werden können. Informationen dazu, wie Sie Ihre Implementierung so strukturieren, dass höhere Volumina durch Parallelisierung verarbeitet werden können, finden Sie in unserem Leitfaden zum Senden mehrerer Anfragen.

  • Kontingentverwaltung: Das Standardkontingent beträgt 1.000.000 Anfragen/Tag und 10.000 Anfragen/Minute. Informationen zum Überwachen und Prüfen Ihrer Kontingente finden Sie unter Kontingente und Limits.

  • E‑Mail-Adresse priorisieren: Geben Sie nach Möglichkeit die emailAddress des Kunden im userIdentifier an. E-Mail-Adressen sind im Allgemeinen die genaueste und zuverlässigste Kennung, um Nutzer ihren Google-Konten zuzuordnen.

  • Leere Antworten verarbeiten: Entwickeln Sie Ihre Anwendung so, dass leere {}-Antworten als Erfolg interpretiert werden. Das bedeutet, dass die Daten aus Datenschutzgründen nicht gespeichert wurden (keine Übereinstimmung oder keine Einwilligung). Wiederholen Sie die Anfrage nicht.

  • Stufenreihenfolge prüfen: Prüfen Sie immer die Reihenfolge Ihrer Treuestufen in der Merchant Center-Benutzeroberfläche, um sicherzustellen, dass Sie in Ihren API-Aufrufen die richtigen Enum-Werte von TIER1 bis TIER7 verwenden. Diese Zuordnung basiert auf der definierten Reihenfolge in der Benutzeroberfläche, nicht auf den Namen.

  • Fehler überwachen: Protokollieren und überwachen Sie API-Antworten. Achten Sie dabei auf 4xx-Fehler, um Integrationsprobleme zu erkennen, insbesondere auf 404-Fehler, die auf eine Diskrepanz beim Verständnis der Stufen hinweisen können.

Zurück
Manage loyalty programs