Übersicht über Treuepunkteprogramme

Präsentieren Sie die Vorteile Ihres Geschäfts auf Google mithilfe von Treuepunkteprogrammen. Sie können eine Reihe von Vorteilen einreichen, z. B. kostenlosen Versand, einlösbare Punkte und exklusive Preise für Mitglieder. Die Vorteile Ihres Treuepunkteprogramms können in Produkteinträgen, Shopping-Anzeigen und Anzeigen für lokales Inventar auf Google-Plattformen wie der Google Suche, dem Shopping-Tab und Google Wallet präsentiert werden.

Mit der Merchant API können Händler und Drittanbieter von Treuepunkteprogrammen, die im Namen von Händlern handeln, Treuepunkteprogramme programmatisch über die LoyaltyProgramService konfigurieren und verwalten. Mit diesem Dienst können Sie Treuepunkteprogramme erstellen, abrufen, auflisten, aktualisieren und löschen.

Wichtig: Der Dienst ist nur für ausgewählte Händler verfügbar. Wenden Sie sich an das Supportteam, um Ihr Interesse an einer Teilnahme zu bekunden. Reichen Sie dazu im Shopping API-Supportformular unter What is the issue/question? eine Zulassungslistenanfrage ein. > Allowlist request > Other (Anfrage zur Aufnahme in die Zulassungsliste > Sonstiges) aus.

Weitere Informationen zu den geschäftlichen Anforderungen und Richtlinien finden Sie in der Merchant Center-Hilfe im Artikel Treuepunkteprogramm des Händlers.

Wichtige Konzepte

Beachten Sie bei der Arbeit mit Treuepunkteprogrammen die folgenden Konzepte und Einschränkungen:

• Kennung auf Kontoebene: Die Merchant API identifiziert Treuepunkteprogramme anhand der Konto-ID des zugehörigen Merchant Center-Kontos.
• Beschränkung auf ein einzelnes Programm: Die Merchant API unterstützt nur ein Treuepunkteprogramm pro Händlerkonto.
• Direkte Kontoinhaberschaft: Treuepunkteprogramme müssen direkt im Ziel-Händlerkonto (accounts/{ACCOUNT_ID}) konfiguriert werden. Der Dienst unterstützt die Verwaltung von Treuepunkteprogrammen auf der Ebene eines erweiterten Kontos für Unterkonten nicht. Drittanbieter von Treueprogrammen mit autorisiertem Zugriff auf das Konto eines Händlers können das Programm im Namen des Händlers verwalten.
• Redaktionelle Überprüfung: Nachdem Sie ein Treuepunkteprogramm erstellt oder aktualisiert haben, wird es überprüft. Das Feld review_result.review_status gibt an, ob das Programm UNDER_REVIEW, APPROVED oder REJECTED ist.
• Unterstützte Regionen: Treuepunkteprogramme von Händlern sind in unterstützten Ländern verfügbar, darunter Deutschland, Australien, Brasilien, Kanada, Frankreich, Indien, Italien, Mexiko, Niederlande, Südkorea, Spanien, Vereinigtes Königreich und USA.
• Anforderungen für Stufen: Für die Teilnahme an Stufen können keine Kosten anfallen, es kann eine Mitgliedsgebühr erforderlich sein, es kann ein Mindestumsatz erforderlich sein oder es kann eine Kreditkarte des Händlers erforderlich sein. Berufsbezogene Stufen (z. B. für Studenten oder Militärangehörige) werden nicht unterstützt.
• Vorteile: Programme unterstützen kostenlosen Versand, einlösbare Punkte und Mitgliedspreise. In Anzeigen muss der Mitgliedspreis mindestens 5 % oder 5 Währungseinheiten unter dem regulären Preis oder Sonderangebotspreis liegen.

Vorbereitung

Bevor Sie Treuepunkteprogramme mit der Merchant API verwalten, müssen die folgenden Voraussetzungen erfüllt sein:

• Sie benötigen ein aktives Merchant Center-Konto (oder autorisierten Zugriff auf das Konto des Händlers, wenn Sie ein Drittanbieter von Treueprogrammen sind).
• Aktivieren Sie das Add-on für das Treuepunkteprogramm für Ihr Konto. Sie können das Add-on mit einer der folgenden Optionen aktivieren:
  • Merchant Center-Benutzeroberfläche: Folgen Sie der Anleitung unter Treuepunkteprogramm einrichten in der Merchant Center-Hilfe.
  • Programs-Sub-API: Aktivieren Sie das Programm programmatisch, wie unter Programme in der Programs-Sub-API aktivieren beschrieben.

Hier ist eine Beispielanfrage zum Aktivieren des Add-ons für das Treuepunkteprogramm mit der Unter-API „Programs“:

HTTP

POST https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/programs/loyalty:enable

cURL

curl --request POST \
  'https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/programs/loyalty:enable?key={YOUR_API_KEY}' \
  --header 'Authorization: Bearer {YOUR_ACCESS_TOKEN}' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{}' \
  --compressed

Methoden

Verwalten Sie Treuepunkteprogramme mit den folgenden Methoden:

• loyaltyPrograms.create
• loyaltyPrograms.get
• loyaltyPrograms.list
• loyaltyPrograms.update
• loyaltyPrograms.delete

Treuepunkteprogramm erstellen

Verwenden Sie die Methode loyaltyPrograms.create, um ein neues Treuepunkteprogramm für ein Konto zu erstellen. Geben Sie Details wie Programmbeschreibungen, die Registrierungs-URL und Programm-Stufen mit ihren jeweiligen Vorteilen und Anforderungen an.

Mit dem erforderlichen program_label wird die eindeutige Kennung für das Treuepunkteprogramm festgelegt. Wenn Sie beispielsweise das Label my-rewards angeben, wird die Ressource name mit accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/my-rewards erstellt.

Hier ein Beispiel für eine Anfrage:

HTTP

POST https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms

{
  "programLabel": "my-rewards",
  "loyaltyProgram": {
    "programName": "my rewards",
    "tiers": [
      {
        "tierName": "gold",
        "tierLabel": "gold",
        "tierBenefits": [
          {
            "otherBenefit": "free gift on your birthday"
          },
          {
            "structuredBenefit": {
              "pointsEarningBenefit": {
                "minimumMoneySpent": {
                  "currencyCode": "USD",
                  "units": "25"
                },
                "pointsEarningBenefitAnnotation": {
                  "pointsEarned": 1.0,
                  "amountSpent": {
                    "currencyCode": "USD",
                    "units": "1"
                  }
                }
              }
            }
          }
        ],
        "requirements": {
          "freeToJoin": true
        }
      }
    ],
    "programDescriptions": [
      "earn rewards buying products you love"
    ],
    "signupUrl": "https://www.example.com/my_rewards_signup",
    "regionCodes": [
      "US"
    ]
  }
}

Ersetzen Sie {ACCOUNT_ID} durch die eindeutige Kennung Ihres Merchant Center-Kontos.

Hier ist eine Beispielantwort für eine erfolgreiche Anfrage:

{
  "name": "accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/my-rewards",
  "programName": "my rewards",
  "tiers": [
    {
      "tierName": "gold",
      "tierLabel": "gold",
      "tierBenefits": [
        {
          "otherBenefit": "free gift on your birthday"
        },
        {
          "structuredBenefit": {
            "pointsEarningBenefit": {
              "minimumMoneySpent": {
                "currencyCode": "USD",
                "units": "25"
              },
              "pointsEarningBenefitAnnotation": {
                "pointsEarned": 1.0,
                "amountSpent": {
                  "currencyCode": "USD",
                  "units": "1"
                }
              }
            }
          }
        }
      ],
      "requirements": {
        "freeToJoin": true
      },
      "signupUrl": "https://www.example.com/my-rewards/gold"
    }
  ],
  "programDescriptions": [
    "earn rewards buying products you love"
  ],
  "signupUrl": "https://www.example.com/my_rewards_signup",
  "reviewResult": {
    "reviewStatus": "UNDER_REVIEW"
  },
  "regionCodes": [
    "US"
  ]
}

Treuepunkteprogramm abrufen

Verwenden Sie die Methode loyaltyPrograms.get, um die Details eines bestimmten selbst verwalteten Treuepunkteprogramms abzurufen.

Hinweis: Auch wenn das Add-on für das Treuepunkteprogramm nicht aktiviert wurde, antwortet dieser Endpunkt mit einem passenden Treuepunkteprogramm, ohne einen Fehler zurückzugeben.

Hier ein Beispiel für eine Anfrage:

HTTP

GET https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/{PROGRAM_LABEL}

Ersetzen Sie {ACCOUNT_ID} durch Ihre Konto-ID und {PROGRAM_LABEL} durch das eindeutige Label des Treuepunkteprogramms (z. B. my-rewards).

Hier ist ein Beispiel für eine Antwort auf eine erfolgreiche Anfrage:

{
  "name": "accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/my-rewards",
  "programName": "my rewards",
  "tiers": [
    {
      "tierName": "gold",
      "tierLabel": "gold",
      "tierBenefits": [
        {
          "otherBenefit": "free gift on your birthday"
        },
        {
          "structuredBenefit": {
            "pointsEarningBenefit": {
              "minimumMoneySpent": {
                "currencyCode": "USD",
                "units": "25"
              },
              "pointsEarningBenefitAnnotation": {
                "pointsEarned": 1.0,
                "amountSpent": {
                  "currencyCode": "USD",
                  "units": "1"
                }
              }
            }
          }
        }
      ],
      "requirements": {
        "freeToJoin": true
      },
      "signupUrl": "https://www.example.com/my-rewards/gold"
    }
  ],
  "programDescriptions": [
    "earn rewards buying products you love"
  ],
  "signupUrl": "https://www.example.com/my_rewards_signup",
  "reviewResult": {
    "reviewStatus": "UNDER_REVIEW"
  },
  "regionCodes": [
    "US"
  ]
}

Treuepunkteprogramme auflisten

Verwenden Sie die Methode loyaltyPrograms.list, um alle eigenen Treuepunkteprogramme aufzulisten, die mit Ihrem Konto verknüpft sind.

Hinweis: Mit dieser Methode werden nur Treuepunkteprogramme aufgeführt, die direkt dem angegebenen Konto gehören, nicht Programme, die mit Unterkonten verknüpft sind. Auch wenn das Add-on für das Treuepunkteprogramm deaktiviert ist, antwortet dieser Endpunkt mit vorhandenen Programmen, ohne einen Fehler zurückzugeben.

Hier ein Beispiel für eine Anfrage:

HTTP

GET https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms

Hier ist eine Beispielantwort für eine erfolgreiche Anfrage:

{
  "loyaltyPrograms": [
    {
      "name": "accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/my-rewards",
      "programName": "my rewards",
      "tiers": [
        {
          "tierName": "gold",
          "tierLabel": "gold",
          "tierBenefits": [
            {
              "otherBenefit": "free gift on your birthday"
            },
            {
              "structuredBenefit": {
                "pointsEarningBenefit": {
                  "minimumMoneySpent": {
                    "currencyCode": "USD",
                    "units": "25"
                  },
                  "pointsEarningBenefitAnnotation": {
                    "pointsEarned": 1.0,
                    "amountSpent": {
                      "currencyCode": "USD",
                      "units": "1"
                    }
                  }
                }
              }
            }
          ],
          "requirements": {
            "freeToJoin": true
          },
          "signupUrl": "https://www.example.com/my-rewards/gold"
        }
      ],
      "programDescriptions": [
        "earn rewards buying products you love"
      ],
      "signupUrl": "https://www.example.com/my_rewards_signup",
      "reviewResult": {
        "reviewStatus": "UNDER_REVIEW"
      },
      "regionCodes": [
        "US"
      ]
    }
  ]
}

Treuepunkteprogramm aktualisieren

Verwenden Sie die Methode loyaltyPrograms.update, um ein vorhandenes Treuepunkteprogramm zu aktualisieren. Führen Sie eine Teilaktualisierung mit einer update_mask durch oder ersetzen Sie die Ressource vollständig, indem Sie die Maske weglassen.

Wichtig: Beim Aktualisieren eines Treuepunkteprogramms können wiederkehrende Felder (z. B. programDescriptions und tiers) nicht direkt aktualisiert werden. Jedes wiederkehrende Feld, das in einer Aktualisierung enthalten ist, ersetzt die gesamte vorhandene Liste. Um unbeabsichtigten Datenverlust zu vermeiden, senden Sie zuerst eine get-Anfrage, um die aktuellen Werte abzurufen, bevor Sie wiederkehrende Felder aktualisieren.

Teilweises Update mit Updatemaske

Mit einer update_mask können Sie die genauen Felder angeben, die aktualisiert werden sollen. Nur die in der Maske aufgeführten Felder werden geändert, während nicht aufgeführte Felder unverändert bleiben. Alle Felder, die nicht in der Aktualisierungsmaske enthalten sind, werden ignoriert, auch wenn sie im Anfragetext angegeben sind.

In der folgenden Beispielanfrage werden nur programDescriptions und advancedSettings aktualisiert:

HTTP

PATCH https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/{PROGRAM_LABEL}?update_mask=program_descriptions,advanced_settings

{
  "programDescriptions": [
    "a new description of the program"
  ],
  "advancedSettings": {
    "hideDisplayFromNonMembers": true
  },
  "signupUrl": "https://www.example.com"
}

In diesem Beispiel ignoriert der Dienst signupUrl, da es nicht in der update_mask enthalten ist. Das Feld programDescriptions ersetzt alle zuvor konfigurierten Beschreibungen vollständig.

Hier ist eine Beispielantwort für eine erfolgreiche Anfrage:

{
  "name": "accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/my-rewards",
  "programName": "my rewards",
  "tiers": [
    {
      "tierName": "gold",
      "tierLabel": "gold",
      "tierBenefits": [
        {
          "otherBenefit": "free gift on your birthday"
        },
        {
          "structuredBenefit": {
            "pointsEarningBenefit": {
              "minimumMoneySpent": {
                "currencyCode": "USD",
                "units": "25"
              },
              "pointsEarningBenefitAnnotation": {
                "pointsEarned": 1.0,
                "amountSpent": {
                  "currencyCode": "USD",
                  "units": "1"
                }
              }
            }
          }
        }
      ],
      "requirements": {
        "freeToJoin": true
      },
      "signupUrl": "https://www.example.com/my-rewards/gold"
    }
  ],
  "programDescriptions": [
    "a new description of the program"
  ],
  "signupUrl": "https://www.example.com/my_rewards_signup",
  "reviewResult": {
    "reviewStatus": "UNDER_REVIEW"
  },
  "regionCodes": [
    "US"
  ],
  "advancedSettings": {
    "hideDisplayFromNonMembers": true
  }
}

Vollständiger Ersatz ohne Aktualisierungsmaske

Wenn Sie den Parameter update_mask weglassen, wird die Konfiguration des Treuepunkteprogramms durch die Anfrage vollständig ersetzt.

Hier ein Beispiel für eine Anfrage:

HTTP

PATCH https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/{PROGRAM_LABEL}

{
  "programName": "Updated Program",
  "signupUrl": "https://example.com/updated",
  "programDescriptions": [
    "Updated description"
  ],
  "regionCodes": [
    "US"
  ],
  "tiers": [
    {
      "tierName": "Gold Tier",
      "tierLabel": "gold",
      "tierBenefits": [
        {
          "otherBenefit": "Free shipping"
        }
      ],
      "requirements": {
        "freeToJoin": true
      }
    }
  ]
}

Hier ist eine Beispielantwort für eine erfolgreiche Anfrage:

{
  "name": "accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/my-rewards",
  "programName": "Updated Program",
  "tiers": [
    {
      "tierName": "Gold Tier",
      "tierLabel": "gold",
      "tierBenefits": [
        {
          "otherBenefit": "Free shipping"
        }
      ],
      "requirements": {
        "freeToJoin": true
      }
    }
  ],
  "programDescriptions": [
    "Updated description"
  ],
  "signupUrl": "https://example.com/updated",
  "reviewResult": {
    "reviewStatus": "UNDER_REVIEW"
  },
  "regionCodes": [
    "US"
  ]
}

Treuepunkteprogramm löschen

Wenn Sie ein Treuepunkteprogramm aus Ihrem Konto löschen möchten, verwenden Sie die Methode loyaltyPrograms.delete.

Hier ein Beispiel für eine Anfrage:

HTTP

DELETE https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/{PROGRAM_LABEL}

Wenn der Vorgang erfolgreich ist, ist der Antworttext leer.

Nächste Schritte

• Informationen dazu, wie Sie einzelne Käufer mit den Stufen Ihres Treuepunkteprogramms verknüpfen, um die Personalisierung in der Google Suche zu ermöglichen, finden Sie im Leitfaden zum Loyalty Customer Match Service.
• Informationen zum Aktivieren oder Deaktivieren von Shopping-Programmen für Ihr Konto finden Sie im Leitfaden zur Unter-API für Programme.
• Weitere Informationen zur Einrichtung des Unternehmens, zu den redaktionellen Richtlinien und zur Berichterstellung finden Sie in der Merchant Center-Hilfe unter Treuepunkteprogramm für Händler.
• Informationen zu API-Methoden und Ressourcendefinitionen finden Sie in der Merchant API-Referenz.