Smart Loyalty Tiers — Vollständige Dokumentation

Einführung

Smart Loyalty Tiers ist ein vollständiges Treueprogramm für WooCommerce. Anders als die meisten Treue-Plugins, die nur einen einfachen Punktezähler für Käufe bieten, liefert Smart Loyalty Tiers 5 verschiedene Verdienstquellen, 4 progressive VIP-Stufen mit konkreten Belohnungen (kostenloser Versand auf Lebenszeit, früher Zugang zu neuen Produkten, Prioritätssupport), ein Gamification-Badge-System und die Umwandlung von Punkten in einmalige WooCommerce-Gutscheine.

Installation und Aktivierung

1. Laden Sie die ZIP-Datei smart-loyalty-tiers.zip aus Ihrem DataFirefly-Kundenbereich herunter.
2. Gehen Sie in WordPress zu Plugins → Installieren → Plugin hochladen.
3. Wählen Sie die ZIP aus und klicken Sie auf Jetzt installieren.
4. Klicken Sie auf Aktivieren.

Bei der Aktivierung erstellt das Plugin automatisch 9 Datenbanktabellen (Präfix wp_slt_), initialisiert die 4 Stufen Bronze / Silver / Gold / Platinum, fügt 10 Standard-Achievement-Badges ein, ergänzt den loyalty-Endpunkt in Mein Konto von WooCommerce und plant 2 Cron-Aufgaben (tägliche Ablaufbehandlung, stündliche Neuberechnung der Stufen).

Einrichtung in 3 Minuten

Nach der Aktivierung erscheint ein neues Menü Loyalty in der Admin-Sidebar mit 5 Unterseiten: Dashboard, VIP-Stufen, Mitglieder, Badges, Einstellungen.

Schritt 1 — Verdienstraten (Loyalty → Einstellungen)

Passen Sie die Standardwerte an Ihre Strategie an:

• Punkte pro ausgegebene Währungseinheit — Standard: 1 (1 Pkt / 1 Einheit)
• Punkte pro Produktbewertung — Standard: 50
• Punkte pro Empfehlung — Standard: 500
• Punkte pro Newsletter-Anmeldung — Standard: 100
• Punkte pro Social Share — Standard: 25

Schritt 2 — Gutschein-Einlösung

• Einlösungsrate — Standard: 100 Punkte = 1 Einheit Rabatt
• Mindesteinlösungsschwelle — Standard: 500 Punkte
• Gutschein-Obergrenze — Standard: 30 % der Warenkorbsumme

Schritt 3 — Anzeige und Gamification

• Punktelabel — Standard: „Punkte“ (z.B. „Meilen“, „Sterne“, „Fireflies“)
• Gamification aktiviert — aktiviert das Feier-Overlay beim Stufen-Upgrade
• E-Mail-Benachrichtigungen — aktiviert Stufen-Upgrade- und Badge-E-Mails

Die 4 VIP-Stufen

Jeder Kunde wird automatisch einer Stufe basierend auf seinen gesamten Lebenszeitpunkten zugeordnet (unabhängig von Einlösungen). Die initialisierten Stufen:

• Bronze — 0 Punkte, keine besonderen Vorteile, Einstiegsstufe
• Silver — 500 Lebenszeitpunkte, x1,25 Punkte-Multiplikator auf Käufe, 12h früher Zugang
• Gold — 2.000 Lebenszeitpunkte, x1,5 Multiplikator, kostenloser Versand, Prioritätssupport, 24h früher Zugang
• Platinum — 5.000 Lebenszeitpunkte, x2 Multiplikator, kostenloser Versand auf Lebenszeit, 48h früher Zugang, exklusive Produkte, 500 Geburtstagsbonus-Punkte

Unter Loyalty → VIP-Stufen ist jede Stufe live mit einem Farbwähler bearbeitbar. Konfigurierbare Vorteile:

• Punkte-Multiplikator (points_multiplier) — automatisch auf alle aus Käufen verdienten Punkte angewendet
• Kostenloser Versand (free_shipping) — WooCommerce Package Rates werden bei der Warenkorbberechnung auf null gesetzt
• Früher Zugang in Stunden (early_access_hours) — wie viele Stunden vor dem Embargo-Datum eines Produkts diese Stufe es sehen und kaufen kann
• Prioritätssupport (priority_support) — fügt ein orangefarbenes Badge zu Admin-Bestellungen hinzu und injiziert einen X-Priority-Header in transaktionale E-Mails
• Geburtstagsbonus (birthday_bonus) — Punkte werden automatisch am Geburtstag des Kunden gutgeschrieben (wenn im Profil hinterlegt)
• Exklusive Produkte (exclusive_products) — aktiviert die Stufen-Filterung auf Produkten, die als exklusiv markiert sind

Die 5 Punktequellen

1. Käufe (PurchaseAction)

Punkte werden gutgeschrieben, wenn die Bestellung in den Status abgeschlossen übergeht (woocommerce_order_status_completed). Die Formel:

punkte = zwischensumme_netto × punkte_pro_währung × stufen_multiplikator

Das System ist idempotent: Es ist unmöglich, zweimal auf derselben Bestellung zu verdienen, selbst wenn der Status wechselt. Bei einer vollständigen oder teilweisen Rückerstattung werden die Punkte automatisch umgekehrt, proportional zum erstatteten Betrag.

2. Produktbewertungen (ReviewAction)

Punkte werden gutgeschrieben, wenn eine genehmigte Bewertung veröffentlicht wird (comment_post oder transition_comment_status → approved). Eine Option „Nur verifizierte Käufer“ beschränkt die Gewinne auf Bewertungen von echten Käufern (Anti-Spam-Schutz).

3. Empfehlungen (ReferralAction)

Jeder Benutzer erhält einen eindeutigen Empfehlungscode und einen Share-Link. Das Tracking erfolgt über einen 30-Tage-Cookie (konfigurierbar über slt_referral_cookie_days). Der Empfehlungsgeber verdient seine Punkte, wenn sein Empfohlener seine erste Bestellung abschließt. Ein optionaler Willkommensbonus wird dem Empfohlenen gutgeschrieben.

4. Newsletter (NewsletterAction)

Zwei Auslösemodi:

• Kontrollkästchen im Checkout — automatisch verwaltet, wenn das Kästchen angekreuzt ist
• Öffentlicher Hook — do_action('slt_newsletter_subscribed', $user_id, $email) — rufen Sie ihn aus Mailchimp, Brevo, MailPoet, Klaviyo oder einem beliebigen System auf

Für ein natives Formular verwenden Sie den Shortcode [slt_newsletter_form].

5. Soziale Shares (SocialShareAction)

7 Plattformen werden über den Shortcode [slt_share_buttons] unterstützt: Facebook, X/Twitter, LinkedIn, Pinterest, WhatsApp, Telegram, E-Mail. Jeder Share wird mit einer Anti-Missbrauchs-Grenze protokolliert:

• Maximal 5 Shares pro Tag pro Benutzer (konfigurierbar)
• Ein und derselbe Share (Benutzer, Plattform, URL) zählt nur einmal

Die konkreten Belohnungen

Kostenloser Versand auf Lebenszeit

Für Stufen mit free_shipping: true werden alle WooCommerce Package Rates bei der Warenkorbberechnung auf null gesetzt. Kein Gutschein zum erneuten Eingeben, keine Manipulation. Ein grüner Hinweis wird automatisch im Warenkorb angezeigt: „✨ Kostenloser Versand — VIP-Status“.

Früher Zugang zu neuen Produkten

Auf jedem Produkt können Sie über eine Metabox „Loyalty früher Zugang“ ein Embargo-Datum festlegen (_slt_embargo_until). Bis das Datum erreicht ist, wird das Produkt:

• Nicht kaufbar für Stufen unterhalb der konfigurierten Schwelle (woocommerce_is_purchasable-Filter)
• Unsichtbar in Listen (woocommerce_product_query-Filter)

Stufen mit early_access_hours > 0 können das Produkt in dem definierten Fenster vor der öffentlichen Embargo-Aufhebung sehen und kaufen. Ein bernsteinfarbenes Banner auf der Einzelproduktseite informiert berechtigte Kunden.

Prioritätssupport

Für Stufen mit priority_support: true erhält jede vom Kunden aufgegebene Bestellung:

• Ein orangefarbenes „Priority“-Badge sichtbar in der Admin-Bestellliste (HPOS und legacy)
• Einen X-Priority: high-Header in transaktionalen E-Mails — nützlich zum Filtern in Ihrem Helpdesk (Zendesk, Freshdesk, Help Scout usw.)

Badge-System (Gamification)

10 Achievement-Badges werden bei der Aktivierung initialisiert:

• First Purchase — erste Bestellung
• Regular Customer — 5 Bestellungen
• Power Buyer — 10 Bestellungen
• Reviewer — erste Bewertung veröffentlicht
• Critic — 10 Bewertungen veröffentlicht
• Brand Ambassador — erste erfolgreiche Empfehlung
• Influencer — 5 erfolgreiche Empfehlungen
• Social Butterfly — 10 Social Shares
• Insider — Newsletter-Anmeldung
• Big Spender — 1.000 Einheiten Lebenszeitausgabe

Unter Loyalty → Badges bearbeiten Sie bestehende oder erstellen neue. Jedes Badge hat ein JSON-Kriterium:

{
  "trigger": "purchase | review | referral | social_share | newsletter | lifetime_spend",
  "count": 5,             // für zählungsbasierte Trigger
  "amount": 1000.00       // für lifetime_spend (Währungsbetrag)
}

Ein Badge kann auch eine Bonus-Punkte-Belohnung beim Freischalten gewähren.

Punkte-Gutschein-Einlösung

Unter Mein Konto → Loyalty gibt der Kunde die Anzahl der umzuwandelnden Punkte ein und klickt auf „Gutschein generieren“. Das Plugin:

1. Erstellt ein einzigartiges einmaliges WC_Coupon-Objekt
2. Beschränkt den Gutschein auf die E-Mail-Adresse des Kunden
3. Setzt eine Ablaufzeit von 30 Tagen
4. Zieht die Punkte vom Saldo ab und protokolliert die Transaktion

Eine slt_max_redemption_percent-Obergrenze (30 % standardmäßig) verhindert, dass der Gutschein einen Prozentsatz der Warenkorbsumme überschreitet — Schutz vor Margen-Verwässerung.

Die 7 Frontend-Shortcodes

[slt_balance]

Zeigt den Punktestand des eingeloggten Kunden an. Optionales Attribut: label="miles".

[slt_balance label="fireflies"]

[slt_tier_badge]

Zeigt den Namen der aktuellen Stufe in einem farbigen Badge an (Stufenfarbe).

[slt_tier_badge]

[slt_progress_bar]

Animierter Fortschrittsbalken zur nächsten Stufe, mit verbleibender Punktezahl und einem Shimmer-Effekt.

[slt_progress_bar]

[slt_tiers_table]

Vergleichstabelle aller Stufen mit ihren Schwellenwerten und Vorteilen — perfekt für eine „Treueprogramm“-Landing-Page.

[slt_tiers_table]

[slt_referral_link]

Zeigt den eindeutigen Empfehlungslink des Kunden + Kopier-Button + Zähler erfolgreicher Empfehlungen.

[slt_referral_link]

[slt_share_buttons]

Social-Share-Buttons. Attribute:

• url — zu teilende URL (Standard: aktuelle Seiten-URL)
• title — zu teilender Titel (Standard: Seitentitel)
• platforms — kommagetrennte Liste (Standard: alle)

[slt_share_buttons platforms="facebook,twitter,whatsapp"]

[slt_newsletter_form]

Newsletter-Anmeldeformular mit automatischer Punktegutschrift bei der Anmeldung.

[slt_newsletter_form title="Abonnieren Sie unseren VIP-Newsletter"]

Kundenbereich (Mein Konto → Loyalty)

Ein neuer Loyalty-Tab wird automatisch nach dem WooCommerce Mein Konto Dashboard hinzugefügt. Der Kunde findet dort:

• Einen farbigen Hero in der Farbe seiner Stufe, mit Saldo und Status
• Seinen Fortschrittsbalken zur nächsten Stufe
• Die Liste seiner aktuellen Vorteile
• Das Gutschein-Einlösungsformular (wenn sein Saldo die Mindestschwelle überschreitet)
• Das Raster aller Badges (verdient in Farbe, gesperrt in Grau)
• Seine vollständige Transaktionshistorie (letzte 25 Einträge standardmäßig)

Admin-Dashboard (Loyalty → Dashboard)

Das Admin-Dashboard zeigt 30-Tage-Statistiken:

• Gesamtzahl der Mitglieder und 30-Tage-Aktive
• Zirkulierende Punkte (Summe der aktiven Salden)
• In 30 Tagen verdiente und eingelöste Punkte
• Abgeschlossene Empfehlungen in 30 Tagen
• Mitgliederverteilung pro Stufe (Balken)
• Neueste Aktivität (letzte 20 Transaktionen aller Mitglieder)

Auf der Mitglieder-Seite können Sie nach einem Kunden suchen, seinen Saldo und seine Stufe sehen, und ihm manuell Punkte anpassen (award oder deduct) über ein AJAX-Modal mit Begründung.

Transaktionale E-Mails

Zwei responsive HTML-E-Mails werden automatisch gesendet:

Stufen-Upgrade

Wird beim Erreichen einer neuen Stufe gesendet. Enthält:

• Ein Banner in der Farbe der neuen Stufe mit einer Trophäe
• Die Liste der neu freigeschalteten Vorteile
• Einen CTA zum Loyalty-Bereich

Die Vorlage kann überschrieben werden, indem sie in ihr-theme/smart-loyalty-tiers/emails/tier-upgrade.php kopiert wird.

Badge erhalten

Wird beim Freischalten eines neuen Badges gesendet, mit Name, Beschreibung und ggf. gutgeschriebenen Bonus-Punkten.

Entwickler-Hooks

Jede Plugin-Aktion feuert Hooks, damit Sie erweitern können, ohne den Code zu berühren:

// Nach Punktevergabe
do_action('slt_points_awarded', $user_id, $points, $source, $reference_id, $reference_type);

// Nach Punkteabzug
do_action('slt_points_deducted', $user_id, $points, $source, $reference_id, $reference_type);

// Stufenwechsel
do_action('slt_tier_upgraded', $user_id, $new_tier, $old_tier);
do_action('slt_tier_downgraded', $user_id, $new_tier, $old_tier);

// Badge freigeschaltet
do_action('slt_badge_awarded', $user_id, $badge);

// Erfolgreiche Empfehlung
do_action('slt_referral_completed', $referrer_id, $referee_id, $order_id);

// Newsletter-Anmeldung (aus Ihrer Integration auslösen)
do_action('slt_newsletter_subscribed', $user_id, $email);

HPOS- und Cart/Checkout-Blöcke-Kompatibilität

Das Plugin deklariert seine HPOS-Kompatibilität automatisch über FeaturesUtil::declare_compatibility(). Alle Bestelldaten-Lesevorgänge nutzen die WooCommerce CRUD-API (wc_get_order()) — keine direkten Abfragen auf wp_posts.

Die Kompatibilität mit Cart– und Checkout-Blöcken ist ebenfalls deklariert. Kostenloser Versand gilt in beiden Modi (klassisch und Blöcke).

Mehrsprachig (Polylang und WPML)

Das Plugin ist vollständig übersetzbar über load_plugin_textdomain mit dem Textdomain smart-loyalty-tiers. Französisch und Englisch sind mitgeliefert, eine vollständige POT-Datei ist für jede andere Sprache enthalten.

Für mehrsprachige Websites:

• Polylang Pro — Stufen- und Badge-Namen können über die Polylang String Translations-Oberfläche übersetzt werden
• WPML — dieselben Strings werden mit WPML über icl_register_string registriert

FAQ und Fehlerbehebung

Ein Kunde sieht seine Punkte nach einer Bestellung nicht gutgeschrieben

Prüfen Sie, ob die Bestellung im Status abgeschlossen ist (das Plugin vergibt keine Punkte bei „in Bearbeitung“ oder „ausstehend“). Wenn der Status korrekt ist, gehen Sie zu Loyalty → Mitglieder, suchen Sie den Kunden und prüfen Sie seinen Verlauf.

Kostenloser Versand wird für einen Gold-Kunden nicht angewendet

Prüfen Sie unter Loyalty → VIP-Stufen, dass der Vorteil „Kostenloser Versand“ auf der Gold-Stufe aktiviert ist. Leeren Sie auch die WooCommerce-Session-Caches (wc_clear_cart_cache()).

Der Mein Konto → Loyalty Endpunkt gibt 404 zurück

Gehen Sie zu Einstellungen → Permalinks und klicken Sie auf „Änderungen speichern“, um die Rewrite-Regeln zu aktualisieren. Dies ist nur einmal nach der Aktivierung nötig.

Cron wird nicht ausgelöst

Auf Sites mit wenig Traffic kann WordPress-Cron unregelmäßig sein. Konfigurieren Sie einen echten System-Cron, um wp-cron.php alle 5–15 Minuten aufzurufen, und deaktivieren Sie den Pseudo-Cron in wp-config.php:

define('DISABLE_WP_CRON', true);

Ein Kunde beschwert sich über abgezogene Punkte nach einer vollständigen Rückerstattung

Das ist normales Verhalten: Bei vollständiger oder teilweiser Rückerstattung werden die entsprechenden Punkte automatisch abgezogen. Wenn der Kunde darauf besteht, können Sie ihm die Punkte manuell über Loyalty → Mitglieder → Anpassen wieder gutschreiben.

Wie deaktiviere ich den Punkteablauf?

Setzen Sie unter Loyalty → Einstellungen die „Ablaufdauer“ auf 0 Tage. Punkte werden nie gelöscht.