# 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,…
- Seite:
- Sprache: de
- Aktualisiert am: 2026-07-01
- Weitere Sprachen: [fr](https://www.datafirefly.com/documentation/smart-loyalty-tiers/index.md), [en](https://www.datafirefly.com/en/documentation/smart-loyalty-tiers/index.md), [es](https://www.datafirefly.com/es/documentation/smart-loyalty-tiers/index.md), [it](https://www.datafirefly.com/it/documentation/smart-loyalty-tiers/index.md), [pl](https://www.datafirefly.com/pl/documentation/smart-loyalty-tiers/index.md), [nl](https://www.datafirefly.com/nl/documentation/smart-loyalty-tiers/index.md), [pt](https://www.datafirefly.com/pt/documentation/smart-loyalty-tiers/index.md)
- Index:
## 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**.
**Kompatibilität:** HPOS-ready, Cart & Checkout Blöcke, Polylang Pro und WPML, WordPress Multisite. Getestet bis WooCommerce 9.5.
## 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).
**Voraussetzungen:** WordPress 6.0+, WooCommerce 7.0+, PHP 7.4+ (8.1+ empfohlen). Das Plugin verweigert die Aktivierung, wenn WooCommerce nicht installiert und aktiv ist.
## 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
Sie können beliebig viele Stufen hinzufügen. Die Neuberechnung erfolgt automatisch bei jedem Punktegewinn, mit einer stündlichen Cron-Sicherung zur Konsistenz.
## 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.
**Support:** Bei Fragen, die hier nicht behandelt werden, kontaktieren Sie unseren Prioritätssupport unter [support@datafirefly.com](mailto:support@datafirefly.com). Antwort innerhalb von 24 Werktagsstunden während Ihres inkludierten Support-Jahres.