Überblick
Im Unterschied zu Stempelkarten mit festem Zielwert bilden Prämien- & Treueprogramme das fortlaufende Punktesammeln sowie mehrstufige Status-Level ab (z. B. Bronze -> Silber -> Gold -> Platin). Passinstance bietet eine Enterprise-Loyalty-Engine mit dynamischen Umsatz-zu-Punkte-Regeln, automatischer Stufenauswertung, APIs für Prämieneinlösungen und Echtzeit-Wallet-Push-Updates.
Backend-Architektur & Loyalty-Engine
Treueprogramme verbinden kontinuierliche Punktekonten mit strukturierten Stufendefinitionen im Passinstance database-Schema:
-
Pass-Typ (pass type):
storeCard(stellt den aktuellen Punktestand gut sichtbar in den primären Kartenbereichen dar). -
Katalog-Demo-Vorlage:
retail-loyalty. -
Mechanik-Typ (mechanic type):
LOYALTY_PROGRAM. -
Zentrale Loyalty-Modelle:
- Tier: Konfiguriert Schwellenwerte (z. B. 500 Punkte für Silber, 1.500 Punkte für Gold), Stufenvorteile, individuelle Kartenfarben und eigene Stufen-Abzeichen. - BalanceChange: Unveränderliches Transaktionsjournal, das jede Punktegutschrift, Einlösung und administrative Anpassung protokolliert.
Punktegutschrift & Stufenaufstiegs-Engine
Pass Mechanics Engine und Tier Progression Engine führen die Loyalty-Regeln zuverlässig aus:
1. Berechnung der Punktegutschrift
Bei einem Einkauf oder Besuch gilt:
-
Der Punkteschritt nutzt standardmäßig
defaultChangeValue(kanonisch), mit Fallback aufconfig.pointsPerScanoder1. -
Bei POS- und E-Commerce-Integrationen werden Punkte dynamisch aus dem Einkaufswert berechnet:
earnedPoints = floor(purchaseTotal * pointsMultiplier)
newBalance = clamp(currentBalance + earnedPoints, minimumValue, maximumValue)
-
Ist
autoResetAtMaximum: trueoderconfig.onCap === "reset"gesetzt, wird der Punktestand beim Erreichen vonmaximumValueaufresetTargetValue(oder den Ausgangsstand) zurückgesetzt.
2. Automatisierte Stufenaufstiege (Tier Progression Engine)
Nach jeder Änderung des Punktestands prüft der Tier Progression Engine die Gesamtpunktzahl gegen die aktiven Stufenschwellen:
-
Wird ein Schwellenwert überschritten, stuft der Service das Mitglied automatisch in die höhere Stufe auf.
-
Das visuelle Design der Karte (Hintergrundfarben, Header-Beschriftungen und Stufen-Abzeichen) wird automatisch angepasst.
-
Ein stiller APNs-Push sowie ein Google-Wallet-REST-Update informieren die Kundschaft mit einer nativen Sperrbildschirm-Benachrichtigung: „Herzlichen Glückwunsch! Sie haben den Gold-Status erreicht.“
API zur Prämieneinlösung
Wenn Kundinnen oder Kunden Punkte im Geschäft oder online gegen Rabatte, Gratisartikel oder Prämien einlösen:
HTTP-Anfrage
/api/v1/mechanics/redeem
{
"passId": "8f94d930-b302-4fc8-9f12-000000000001",
"mechanicId": "4a71b2d0-5e3a-4e8c-8f21-000000000002",
"idempotencyKey": "redeem_tx_88194"
}
HTTP-Antwort (200 OK)
{
"success": true,
"newBalance": 240,
"newBalanceDecimal": "240",
"message": "Reward redeemed successfully"
}
E-Commerce- & Multi-Channel-Synchronisierung
Verbinden Sie Kassen im stationären Handel mit Online-Shops, um ein einheitliches Kundenkonto zu führen (transaction type: EARN, REDEEM, ADJUST, REFUND, TRANSFER, BONUS, PENALTY, SCAN, API, ADJUSTMENT):
-
Shopware 6- / Shopify-Konnektoren: Verarbeiten Sie Online-Bestell-Webhooks (
/api/v1/automations/webhooks/shopify/:customerId,/api/v1/automations/webhooks/woocommerce/:customerIdoder Shopware-Plugin-Webhooks) und schreiben Sie Kundenpässen überexternalIdautomatisch Punkte gut. -
Kanonische Pass-Use-API (
POST /api/v1/passes/:id/use): Bevorzugter programmatischer Endpunkt für ERPs, Apps und Backend-Services zur Anpassung von Punkten/Guthaben (mit dem Scanner-Key-PendantPOST /api/v1/scans/pass/:passId/use). Der ältere EndpunktPOST /api/v1/mechanics/:mechanicId/eventswird aus Kompatibilitätsgründen weiterhin unterstützt, ist für neue Integrationen jedoch als veraltet eingestuft.
Wichtig: Konfigurieren Sie im Vorlageneditor auf Ihrem primären Punktefeld
changeMessage: "Punktestand aktualisiert: %@". Bei jeder Gutschrift oder Einlösung zeigt der Sperrbildschirm Ihrer Kundschaft umgehend den neuen Kontostand an.
Erfahren Sie mehr über unsere Loyalty-Lösung, entdecken Sie Treuekarten oder lesen Sie den Leitfaden zu Loyalty-Fortschrittsregeln.
