Skip to content
Hilfecenter-Anleitung
3 Min. LesezeitGeprüft 2026-11-16

Prämien- & Treueprogramme

Gestalten Sie mehrstufige Punkte- und Tier-Programme mit Umsatz-zu-Punkte-Regeln, Statusaufstiegen und Push-Benachrichtigungen.

In dieser Anleitung

Ü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.

SYSTEMARCHITEKTUR-ABLAUF
INTERAKTIVE ARCHITEKTUR
PUNKTEGUTSCHRIFT & STUFENAUFSTIEG
BETEILIGTE SYSTEMKOMPONENTEN
P1 POS / E-Commerce-Kauf
P2 Passinstance Core API
P3 Tier Progression Engine
P4 Kunden-Wallet-Pass
SCHRITT CTX KONTEXT Einkauf: 120 €120 Pkt
SCHRITT 1 ANFRAGE / AKTION POST/api/v1/passes/:id/use
SCHRITT 2 ANFRAGE / AKTION Stand aktualisieren
›
{ action: "INCREMENT", value }
›
(cur + step begrenzt)
SCHRITT 3 ANFRAGE / AKTION Stufen prüfen
›
(Schwelle erreicht:
›
SilberGold)
SCHRITT 4 ANTWORT Stufe erhöht
SCHRITT 5 ANFRAGE / AKTION Stiller APNs-Push
SCHRITT 6 ANTWORT 200 OK (Neue Stufe)
›
& Google REST PATCH | (Karte wechselt zu Gold
›
Sperrbildschirm-Hinweis:
›
"Aufstieg auf Gold!")

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 auf config.pointsPerScan oder 1.
  • Bei POS- und E-Commerce-Integrationen werden Punkte dynamisch aus dem Einkaufswert berechnet:
TEXT
earnedPoints = floor(purchaseTotal * pointsMultiplier)
  newBalance = clamp(currentBalance + earnedPoints, minimumValue, maximumValue)
  • Ist autoResetAtMaximum: true oder config.onCap === "reset" gesetzt, wird der Punktestand beim Erreichen von maximumValue auf resetTargetValue (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

POST /api/v1/mechanics/redeem
Header
X-API-Key <API_KEY>
Content-Type application/json
JSON
{
  "passId": "8f94d930-b302-4fc8-9f12-000000000001",
  "mechanicId": "4a71b2d0-5e3a-4e8c-8f21-000000000002",
  "idempotencyKey": "redeem_tx_88194"
}

HTTP-Antwort (200 OK)

JSON
{
  "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/:customerId oder Shopware-Plugin-Webhooks) und schreiben Sie Kundenpässen über externalId automatisch 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-Pendant POST /api/v1/scans/pass/:passId/use). Der ältere Endpunkt POST /api/v1/mechanics/:mechanicId/events wird 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.

Bereit für Ihr erstes Wallet-Kartenprogramm?

Erstellen Sie Ihren Workspace, konfigurieren Sie Ihre Vorlage und testen Sie eine echte Karte in Apple Wallet und Google Wallet, bevor Sie skalieren.