Ü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 exklusive Preise 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. Wenn Sie an einer Teilnahme interessiert sind, wenden Sie sich an das Supportteam und reichen Sie im Supportformular für Shopping-APIs unter What is the issue/question? (Was ist das Problem/die Frage?) eine Zulassungs anfrage ein. > Antrag auf Zulassungsliste > Sonstiges

Weitere Informationen zu den Geschäftsanforderungen 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 Treueprogramm 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:Die Teilnahme an Stufen kann kostenlos sein, eine Mitgliedsgebühr, einen Ausgabenschwellenwert oder eine Kreditkarte mit Händlerlogo erfordern. 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 Sie die folgenden Anforderungen erfüllen:

• Sie müssen ein aktives Merchant Center-Konto haben oder als Drittanbieter für Treuepunkteprogramme autorisierten Zugriff auf das Konto des Händlers haben.
• 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 unter Treuepunkteprogramm einrichten in der Merchant Center-Hilfe.
  • 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 die 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

Wenn Sie die Details eines bestimmten Treuepunkteprogramms abrufen möchten, das Ihnen gehört, verwenden Sie die Methode loyaltyPrograms.get.

Hinweis :Auch wenn das Add-on für Treuepunkteprogramme nicht aktiviert wurde, gibt dieser Endpunkt weiterhin ein passendes Treuepunkteprogramm zurück, ohne einen Fehler auszugeben.

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, werden bei diesem Endpunkt vorhandene Programme zurückgegeben, ohne dass ein Fehler auftritt.

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

Mit der Methode loyaltyPrograms.update können Sie ein vorhandenes Treuepunkteprogramm 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 :Wenn Sie ein Treuepunkteprogramm aktualisieren, können wiederholte Felder (z. B. programDescriptions und tiers) nicht direkt aktualisiert werden. Jedes wiederholte Feld, das in einer Aktualisierung enthalten ist, ersetzt die gesamte vorhandene Liste. Um unbeabsichtigten Datenverlust zu vermeiden, sollten Sie vor dem Aktualisieren von Feldern mit Wiederholungen zuerst eine get-Anfrage senden, um die aktuellen Werte abzurufen.

Teilweises Update mit Aktualisierungsmaske

Mit einer 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.

Mit 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 er nicht in 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 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

• 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 Leitfaden zur Unter-API 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.