Übersicht über Treuepunkteprogramme

Mit Treuepunkteprogrammen können Sie die Vorteile Ihres Geschäfts auf Google präsentieren. Sie können eine Reihe von Vorteilen einreichen, z. B. kostenlosen Versand, einlösbare Punkte und Preise nur für Mitglieder. Die Vorteile Ihres Treuepunkteprogramms können in Produkteinträgen, Shopping-Anzeigen und Anzeigen für lokales Inventar in verschiedenen Google-Produkten 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, wenn Sie an einer Teilnahme interessiert sind. Reichen Sie dazu eine Zulassungsanfrage im Shopping API-Supportformular unter What is the issue/question? > Antrag auf Zulassungsliste > Sonstiges

Weitere Informationen zu den geschäftlichen Anforderungen und Richtlinien finden Sie in der Merchant Center-Hilfe unter Treuepunkteprogramm für Händler.

Wichtige Konzepte

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

• Kennung auf Kontoebene:In der Merchant API werden Treuepunkteprogramme anhand der ID des zugehörigen Merchant Center-Kontos identifiziert.
• Beschränkung auf ein Programm:Die Merchant API unterstützt nur ein Treuepunkteprogramm pro Händlerkonto.
• Direkte Kontoinhaberschaft:Treuepunkteprogramme müssen direkt im Zielhändlerkonto (accounts/{ACCOUNT_ID}) konfiguriert werden. Die Verwaltung von Treuepunkteprogrammen auf einer erweiterten Kontoebene für untergeordnete Konten wird vom Dienst nicht unterstützt. Drittanbieter von Treuepunkten 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 für Händler sind in unterstützten Ländern verfügbar, darunter Deutschland, Australien, Brasilien, Frankreich, Indien, Italien, Kanada, Mexiko, Niederlande, Südkorea, Spanien, Vereinigtes Königreich und USA.
• Stufenanforderungen:Für die Teilnahme an Stufen können keine Kosten anfallen, es kann ein Mitgliedsbeitrag, ein Ausgabenschwellenwert oder eine Kreditkarte mit Händlerlogo 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 ist für Mitgliedspreise ein Rabatt von mindestens 5% oder 5 Währungseinheiten unter dem regulären Preis oder Sonderangebotspreis erforderlich.

Vorbereitung

Bevor Sie Treuepunkteprogramme mit der Merchant API verwalten, müssen Sie die folgenden Anforderungen erfüllen:

• 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.
• Aktivieren Sie das Add‑on für das Treuepunkteprogramm für Ihr Konto. Sie haben folgende Möglichkeiten, das Add-on zu aktivieren:
  • Merchant Center-Benutzeroberfläche:Folgen Sie der Anleitung im Hilfeartikel Treuepunkteprogramm einrichten.
  • Unter-API für Programme:Aktivieren Sie das Programm programmatisch, wie unter Programme in der Unter-API für Programme aktivieren beschrieben.

Hier ist eine Beispielanfrage zum Aktivieren des Add-ons für Treuepunkteprogramme 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

Sie können Treuepunkteprogramme mit den folgenden Methoden verwalten:

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

Treuepunkteprogramm erstellen

Verwenden Sie zum Erstellen eines neuen Treuepunkteprogramms für ein Konto die Methode loyaltyPrograms.create. Geben Sie Details wie Programmbeschreibungen, die Registrierungs-URL und Programmstufen mit ihren einzigartigen 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, erhalten Sie eine Ressource name mit dem Wert accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/my-rewards.

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 ein Beispiel 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 Treuepunkteprogramms abzurufen, das Ihnen gehört.

Hinweis :Auch wenn das Add-on für Treuepunkteprogramme nicht aktiviert wurde, wird bei diesem Endpunkt weiterhin ein passendes Treuepunkteprogramm zurückgegeben, ohne dass ein Fehler ausgegeben wird.

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 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 Treuepunkteprogramme aufzulisten, die mit Ihrem Konto verknüpft sind.

Hinweis :Bei dieser Methode werden nur Treuepunkteprogramme aufgeführt, die direkt dem angegebenen Konto gehören, nicht Programme, die mit untergeordneten Konten verknüpft sind. Auch wenn das Add-on für Treuepunkteprogramme deaktiviert ist, gibt dieser Endpunkt vorhandene Programme zurück, ohne einen Fehler zu melden.

Hier ein Beispiel für eine Anfrage:

HTTP

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

Hier ist ein Beispiel 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 einem update_mask durch oder führen Sie einen vollständigen Ersatz durch, indem Sie die Maske weglassen.

Wichtig :Beim Aktualisieren eines Treuepunkteprogramms können wiederholte Felder (z. B. programDescriptions und tiers) nicht direkt aktualisiert werden. Alle wiederholten Felder, die in einer Aktualisierung enthalten sind, ersetzen die gesamte vorhandene Liste. Um unbeabsichtigte Datenverluste zu vermeiden, sollten Sie vor dem Aktualisieren von Feldern mit Wiederholungen zuerst eine get-Anfrage senden, um die aktuellen Werte abzurufen.

Teilaktualisierung mit Aktualisierungsmaske

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

Im folgenden Beispiel 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 update_mask enthalten ist. Das Feld programDescriptions ersetzt alle zuvor konfigurierten Beschreibungen vollständig.

Hier ist eine Beispielantwort 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": [
    "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 auf 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

• Wenn Sie einzelne Käufer mit Ihren Treuepunkteprogrammstufen für die organische Personalisierung in der Google Suche verknüpfen möchten, lesen Sie den Leitfaden zum Loyalty Customer Match Service.
• Informationen zum Aktivieren oder Deaktivieren von Shopping-Programmen für Ihr Konto finden Sie im Unter-API-Leitfaden für Programme.
• Weitere Informationen zur Einrichtung, zu redaktionellen Richtlinien und zu Berichten 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.