Empfehlungspraemien

Uebersicht

Das Empfehlungspraemiensystem in TanStack Ship foerdert das Benutzerwachstum, indem es bestehende Benutzer dazu anregt, neue Benutzer auf die Plattform einzuladen. Es basiert auf einem dualen Praemienmodell, bei dem sowohl der empfehlende Benutzer (Einladender) als auch der neu eingeladene Benutzer nach erfolgreicher Konversion Gutschriftpraemien erhalten, wodurch eine fuer beide Seiten vorteilhafte virale Wachstumsschleife entsteht, die die Kundenakquisitionskosten senkt.

Als Teil der TanStack Ship Plattform integriert sich das Empfehlungspraemiensystem in das Einladungssystem (Verfolgung, wer wen eingeladen hat), das Guthabensystem (Auszahlung von Praemien als ausgebbare Punkte) und das Benutzer-Dashboard (Bereitstellung von Transparenz ueber Empfehlungsstatus und Praemienguthaben). Das System verarbeitet Praemien mit Idempotenzgarantien und stellt sicher, dass jede erfolgreiche Empfehlung unabhaengig von Wettlaufbedingungen oder Wiederholungsszenarien genau einmal ausgezahlt wird.

Design-Ablauf

Das Empfehlungspraemiensystem automatisiert den gesamten Praemienlebenszyklus von der Ereignisausloesung ueber die idempotente Auszahlung bis zur Pruefprotokollierung:

Kernfunktionen

Doppelte Praemienstruktur

Wenn ein neuer Benutzer ueber einen Empfehlungslink registriert, zahlt das System automatisch Praemien an beide Parteien aus:

Diese duale Anreizstruktur schafft einen leistungsstarken Wachstumsmechanismus — bestehende Benutzer werden motiviert, ihre Empfehlungslinks zu teilen, waehrend neue Benutzer sofort nach dem Beitritt einen Mehrwert erhalten, was sowohl die Empfehlungsrate als auch die Zufriedenheit der Erstbenutzer steigert.

Clientseitiges Empfehlungsstatus-Beispiel:

import { useQuery } from '@tanstack/react-query'

export function ReferralStatus() {
  const { data } = useQuery({
    queryKey: ['referral-stats'],
    queryFn: () =>
      fetch('/api/referrals/stats').then((r) => r.json()) as Promise<{
        totalRewardsEarned: number
        successfulReferrals: number
        pendingRewards: number
      }>,
  })

  return (
    <div className="rounded-lg border p-4">
      <h3 className="mb-3 font-semibold">Deine Empfehlungspraemien</h3>
      <dl className="grid grid-cols-3 gap-4">
        <div>
          <dt className="text-xs text-muted-foreground">Verdient</dt>
          <dd className="text-xl font-bold">{data?.totalRewardsEarned ?? '—'}</dd>
        </div>
        <div>
          <dt className="text-xs text-muted-foreground">Empfehlungen</dt>
          <dd className="text-xl font-bold">{data?.successfulReferrals ?? 0}</dd>
        </div>
        <div>
          <dt className="text-xs text-muted-foreground">Ausstehend</dt>
          <dd className="text-xl font-bold">{data?.pendingRewards ?? 0}</dd>
        </div>
      </dl>
    </div>
  )
}

Konfigurierbare Praemienverwaltung

Administratoren koennen Praemienparameter ueber das Admin-Dashboard unter /dashboard/admin/credits/invite-reward konfigurieren:

• Praemienbetrag fuer Einladende — Legen Sie die Anzahl der Guthabenpunkte fest, die dem empfehlenden Benutzer gutgeschrieben werden
• Begruessungsbetrag fuer neue Benutzer — Konfigurieren Sie den Willkommensbonus fuer neu eingeladene Benutzer
• Praemienschalter — Aktivieren oder deaktivieren Sie das Praemiensystem global, ohne die bestehende Einladungsverfolgung zu beeintraechtigen
• Auszahlungshistorie — Zeigen Sie detaillierte Transaktionsprotokolle mit Zeitstempeln und Benutzerzuordnung fuer alle Praemienauszahlungen an
• Schwellenwertkonfiguration — Optional koennen Sie verlangen, dass der Einladende ein aktives Abonnement hat, damit Praemien gewaehrt werden, um Missbrauch zu verhindern

Idempotente Praemienverarbeitung

Das Praemiensystem ist mit Idempotenz als Kernzuverlaessigkeitsmerkmal konzipiert:

Wenn eine einzelne Empfehlung mehrmals verarbeitet wird — sei es aufgrund von Webhook-Wiederholungen, Nebenlaeufigkeits-Wettlaufbedingungen oder Datenbankreplikationsverzoegerungen — stellt das System sicher, dass die Praemie genau einmal ausgezahlt wird. Dies wird durch eindeutige Constraint-Erzwingung auf der Empfehlungs-zu-Praemien-Zuordnung in der Datenbank in Kombination mit transaktionaler Verarbeitung in der Praemienauszahlungslogik erreicht.

Transaktionshistorie und Pruefpfad

Alle Praemienoperationen werden im Transaktionsprotokoll dokumentiert und bieten vollstaendige Transparenz:

• Praemienbetrag und Typklassifizierung (Einladendenpraemie vs. neuer Benutzer-Begruessungspraemie)
• Zugehoeriger Empfehlungsdatensatz mit Einladenden- und Eingeladenen-Identifikatoren
• Verarbeitungszeitstempel mit genauer chronologischer Reihenfolge
• Statusverfolgung (ausstehend, abgeschlossen, fehlgeschlagen) mit Erfassung des Fehlergrunds
• Administratorpruefungsoberflaeche fuer manuellen Abgleich bei Bedarf

Design-Philosophie

Duales Anreiz-Wachstumsmodell

Das Empfehlungspraemiensystem ist um eine duale Anreizstruktur herum konzipiert, die sowohl den Empfehlungsgeber als auch den empfohlenen Benutzer belohnt. Dies erzeugt eine leistungsstarke virale Akquiseschleife: Bestehende Benutzer werden durch konkrete Guthabenpraemien zu Markenbotschaftern, waehrend neue Benutzer sofort nach dem Beitritt einen Mehrwert erhalten, was die Konversionsrate von Empfehlungsverkehr erhoeht. Das konfigurierbare Belohnungsverhaeltnis ermoeglicht es Plattformbetreibern, das Gleichgewicht zwischen Akquisitionskosten und Empfehlungsgeschwindigkeit basierend auf ihrer spezifischen Wachstumsoekonomie zu optimieren.

Idempotenz-zuerst-Zuverlaessigkeit

Jede Praemienauszahlung ist durch Idempotenzgarantien geschuetzt, die auf Datenbankebene durch einzigartige Constraints auf der Empfehlungs-zu-Praemien-Zuordnung erzwungen werden. Ob ein Empfehlungsereignis aufgrund von Webhook-Wiederholungen, Nebenlaeufigkeits-Wettlaufbedingungen oder Systemausfaellen einmal oder hundertmal verarbeitet wird, die Praemie wird genau einmal ausgezahlt. Dieser Idempotenz-zuerst-Ansatz ist grundlegend fuer die Zuverlaessigkeit des Systems — er eliminiert eine ganze Klasse von Auszahlungsfehlern, ohne komplexe verteilte Sperren oder externe Koordination zu erfordern. Im Gegensatz zu ReferralCandy — das auf externe API-Idempotenz mit Netzwerkabhaengigkeiten angewiesen ist — verwendet unsere Praemienverarbeitung einzigartige Constraints auf Datenbankebene innerhalb Ihrer eigenen Infrastruktur, um sicherzustellen, dass Auszahlungsgarantien auch bei Netzwerkpartitionen bestehen bleiben.

Konfigurierbare Praemienoekonomie

Praemienbetraege, Berechtigungskriterien und Auszahlungsbedingungen sind vollstaendig ueber das Admin-Dashboard konfigurierbar, ohne Codeaenderungen. Dies ermoeglicht es Plattformbetreibern, Experimente durchzufuehren — Praemiengroessen anzupassen, Berechtigungsschwellen zu testen oder Praemien voruebergehend zu deaktivieren — und die Auswirkungen auf Akquisitionskennzahlen in Echtzeit zu beobachten. Das Transaktionsprotokoll des Systems liefert die Daten, die zur Berechnung der Kosten pro Akquisition und des Return on Investment fuer das Empfehlungsprogramm erforderlich sind.

Best Practices

Optimale Praemiengroesse

Legen Sie Praemienbetraege fest, die bedeutend genug sind, um zum Teilen zu motivieren, aber fuer Ihre Einheitsoekonomie nachhaltig sind. Ein haeufiges Verhaeltnis ist 2,5:1 zwischen Einladenden- und Neubenutzerpraemien (z. B. 500 Punkte fuer den Einladenden, 200 Punkte fuer den neuen Benutzer). Ueberwachen Sie die Kosten pro Akquisition ueber das Attributionsanalyse-Dashboard und passen Sie die Praemienbetraege basierend auf der Kanalleistung an.

Missbrauchspraevention

Implementieren Sie Berechtigungsanforderungen, um das Austricksen des Systems zu verhindern. Uebliche Sicherheitsmassnahmen umfassen die Anforderung, dass der Einladende ein aktives Abonnement oder ein Mindestkontenalter haben muss, bevor Praemien ausgezahlt werden koennen. Das System unterstuetzt konfigurierbare Schwellenwertpruefungen, die ueber das Admin-Dashboard aktiviert werden koennen.

Transparente Kommunikation

Zeigen Sie beiden Parteien — Einladenden und Eingeladenen — klare Empfehlungspraemienbedingungen an. Das Benutzer-Dashboard sollte die genauen Praemienbetraege, Auszahlungsbedingungen und den aktuellen Status ausstehender Praemien anzeigen. Transparenz schafft Vertrauen und foerdert mehr Teilen.

Ueberwachung und Optimierung

Verfolgen Sie wichtige Empfehlungskennzahlen — Empfehlungskonversionsrate, durchschnittliche Praemienkosten pro akquiriertem Benutzer und den Lifetime Value empfohlener Benutzer. Verwenden Sie diese Kennzahlen, um Praemienbetraege und Berechtigungskriterien zu optimieren. Der Pruefpfad des Systems liefert die fuer diese Analyse erforderlichen Daten.

Haeufig gestellte Fragen

Wie funktioniert das Empfehlungspraemiensystem? Wenn ein bestehender Benutzer seinen Empfehlungslink teilt und ein neuer Benutzer ueber diesen Link registriert, erhalten beide Parteien Guthabenpraemien. Der Einladende erhaelt eine Praemie fuer die erfolgreiche Empfehlung, und der neue Benutzer erhaelt einen Begruessungsbonus fuer den Beitritt ueber die Empfehlung.

Kann ich Praemienbetraege aendern, nachdem das System live ist? Ja. Praemienbetraege sind ueber das Admin-Dashboard unter /dashboard/admin/credits/invite-reward konfigurierbar. Aenderungen werden sofort fuer alle zukuenftigen Empfehlungen wirksam. Historische Empfehlungsauszahlungen sind nicht betroffen.

Was passiert, wenn ein Benutzer versucht, sich selbst zu empfehlen? Das System verhindert Selbstempfehlungen durch IP-Verfolgung und Kontovalidierung. Wenn ein Benutzer versucht, seinen eigenen Einladungscode waehrend der Registrierung zu verwenden, lehnt das System die Empfehlung ab und es werden keine Praemien verarbeitet.

Sind Praemien fuer Benutzer steuerpflichtig? Die steuerlichen Auswirkungen haengen von Ihrer Rechtsordnung und der Art der Praemien ab (virtuelle Punkte vs. echtes Geld). Konsultieren Sie Ihr Rechtsteam bezueglich der steuerlichen Behandlung von Empfehlungspraemien in Ihren Betriebsregionen.

Wie verhindert Idempotenz doppelte Praemien? Das System verwendet einzigartige Constraints auf Datenbankebene fuer die Kombination aus Einladungs-ID und Praemientyp. Wenn dasselbe Empfehlungsereignis zweimal verarbeitet wird, schlaegt der zweite Versuch aufgrund der Constraint-Verletzung fehl, und es wird keine doppelte Praemie erstellt.

Koennen Praemien von Administratoren manuell angepasst werden? Ja. Administratoren koennen ueber die Admin-Oberflaeche des Guthabensystems manuelle Guthabentransaktionen erstellen, um Praemien bei Bedarf anzupassen, z. B. zur Kompensation von Grenzfaellen oder zur Verarbeitung rueckwirkender Praemien.

Welche Berichte sind fuer die Empfehlungsleistung verfuegbar? Der Empfehlungspraemienbereich des Admin-Dashboards bietet Auszahlungshistorie, Empfehlungserfolgsraten, insgesamt ausgezahlte Praemien und benutzerspezifische Empfehlungsstatistiken. Diese Daten koennen mit dem Attributionsanalysesystem fuer eine umfassende Wachstumsanalyse abgeglichen werden.

Konfiguration

Verwalten Sie Empfehlungspraemien ueber das Admin-Dashboard unter /dashboard/admin/credits/invite-reward. Konfigurationsoptionen umfassen:

• Praemienbetrag fuer Einladende (in Guthabenpunkten)
• Begruessungsbetrag fuer neue Benutzer (in Guthabenpunkten)
• Globaler Aktivierungs-/Deaktivierungsschalter
• Berechtigungsanforderungen (Abonnementstatus, Mindestkontenalter)

Praemien werden ueber das Guthabensystem ausgezahlt, das aktiv sein muss. Fuer die Kernfunktionalitaet der Praemien sind keine zusaetzlichen Umgebungsvariablen erforderlich.

Integrationspunkte

Das Empfehlungspraemiensystem integriert sich mit den folgenden TanStack Ship Plattformmodulen:

• Einladungssystem — Empfehlungspraemien werden ausgeloest, wenn ein Einladungscode waehrend der Registrierung eines neuen Benutzers erfolgreich eingeloest wird
• Guthabensystem — Praemien werden als Guthabenpunkte ueber das Guthabentransaktionssystem ausgezahlt und erscheinen zusammen mit Kaeufen und Kampagnenboni in der Guthabenhistorie des Benutzers
• Benutzer-Dashboard — Benutzer koennen ihren Empfehlungsstatus verfolgen, ausstehende und abgeschlossene Praemien einsehen und ihre Gesamteinnahmen aus Empfehlungen ueberwachen
• Kampagnen & Angebote — Empfehlungskampagnen koennen waehrend Aktionszeitraeumen mit zusaetzlichen Bonusangeboten verstaerkt werden
• Attributionsanalyse — Empfehlungsgesteuerte Akquisitionen werden als attribuierte Konversionen verfolgt und bieten Transparenz ueber die Leistung und Kosteneffektivitaet dieses Wachstumskanals