Skip to content
Hilfecenter-AnleitungOnboarding-Phase 2
3 Min. LesezeitGeprüft 2026-11-16

Treue- & Stempelkarten

Erstellen Sie digitale Stempelkarten mit visuellem Raster, Punktezuwachs pro Besuch und automatischen Prämienauslösern.

In dieser Anleitung

Prüfen Sie passende Dashboard-Bereiche, Steuerelemente und Zoom-Hinweise zu diesem Thema.

Vergrößerter UI-Fokus
Wichtige UI-Elemente

Auswahl „Add a Pass Mechanic“ (Zoom)

Wählen Sie aus 6 integrierten Mechaniken: Stempelkarte, Stempel-Einlösung, Guthaben (Stored Value), Punkte & Stufen, Einmal-pro-Tag-Validierung oder Laufzeitverlängerung.

Überblick

Treue- & Stempelkarten digitalisieren klassische Papier-Stempelkarten („8 Kaffees kaufen, den 9. gratis erhalten“) als interaktive native Wallet-Pässe. Kundinnen und Kunden verlieren ihre Karte nie wieder, Mitarbeitende verbuchen Besuche per optischem QR-Scan in zwei Sekunden und Unternehmen fördern Wiederbesuche über automatisierte Sperrbildschirm-Mitteilungen.

Backend-Architektur & Mechanik-Enums

Digitale Stempelkarten kombinieren dynamische Strip-Grafiken mit deterministischer Regelausführung im Pass Mechanics Engine:

  • Pass-Typ (pass type): storeCard.
  • Katalog-Demo-Vorlagen: restaurant-stamp-card und coffee-loyalty.
  • Mechanik-Typen (mechanic type):

- STAMP_CARD_ADD: Erhöht den aktiven Stempelstand um defaultChangeValue (typischerweise 1). - STAMP_CARD_DEDUCT: Ermöglicht dem Kassenpersonal die Korrektur versehentlicher Stempel oder das Abziehen von Stempeln bei Teileinlösungen.

  • Konfiguration des visuellen Stempelrasters:

- StampImage-Array: Ordnet den Stempelpositionen 0..N individuelle Bildzustände zu (gerendert auf Apple-Strip-Grafiken und modularen Google-Wallet-Bildern). - maximumValue: Gesamtanzahl benötigter Stempel bis zur vollen Karte (z. B. 8 oder 10). - rewardImageResourceId: Individuelles Pokal- oder Prämiensymbol, das bei vollständiger Stempelkarte eingeblendet wird.

SYSTEMARCHITEKTUR-ABLAUF
INTERAKTIVE ARCHITEKTUR
STEMPELKARTEN-ZYKLUS & OBERGRENZEN
STUFE 01 FORTSCHRITTS-PIPELINE
1
Erster Scan (0 Stempel)
2
+1 Stempel pro Besuch
3
Karte erreicht maximumValue (z. B. 8)
STUFE 02A onCap: "noop"
Karte bleibt bei 8/8
Aktion: NOOP
Personal löst Prämie ein
STUFE 02B onCap: "reset"
Prämie gewährt
Zähler springt auf 0
Neuer Zyklus startet sofort
STUFE 02C Standard-Validierung
Liefert HTTP 400
"Stempelkarte ist voll; zuerst Prämie einlösen"

Ausführungslogik der Stempel-Engine & Obergrenzen-Verhalten

Wenn eine Mitarbeiterin oder ein Mitarbeiter den Pass scannt, prüft der Pass Mechanics Engine die aktiven Schwellenwerte:

  1. 1
    Stempel-Inkrement: Addiert defaultChangeValue (Standard 1) zum aktuellen Pass-Stand:
TEXT
newStamps = clamp(currentStamps + defaultChangeValue, 0, maximumValue)
  1. 2
    Verhalten bei Erreichen des Limits (onCap) & Aktionssemantik (scan action / transaction type):

- onCap: "noop": Erreicht die Karte die maximale Stempelzahl, gibt die Engine { ok: true, reason: "Card is full", appliedAction: "NOOP" } zurück. Der volle Kartenstand bleibt sichtbar, damit das Personal die abgeschlossene Karte prüfen und die Prämie aushändigen kann. - onCap: "reset": Löst automatisch das Prämienereignis aus und setzt die Stempel auf 0 zurück: { ok: true, reason: "Card reset" }. - Standardverhalten: Gibt { ok: false, reason: "Stamp card is full" } zurück und fordert das Personal auf, den separaten Einlöseprozess anzustoßen (POST /api/v1/mechanics/redeem oder POST /api/v1/passes/:id/use mit scan action: INCREMENT, DECREMENT, VALIDATE, protokolliert mit transaction type: EARN, REDEEM, ADJUST, SCAN).

  1. 3
    Verhalten bei Prämieneinlösung (rewardClaimBehavior):

- RESET_TO_ZERO: Setzt bei Einlösung durch das Personal alle Stempel auf 0 zurück. - START_NEW_CYCLE: Überträgt überschüssige Stempel aus größeren Einkäufen direkt in den nächsten Prämienzyklus. - KEEP_COMPLETED: Behält den vollständigen visuellen Zustand bei, bis der Prämien-Coupon eingelöst wurde.

  1. 4
    CRM-Korrelation (externalId): Verknüpfen Sie Ihre Kunden- bzw. Treueprogramm-ID mit Pass.externalId, damit POS, Webshop und mobile App Stempelaktualisierungen sauber über POST /api/v1/passes/upsert-by-external-id synchronisieren können.
Kartenauswahl für Vorlagen-Mechaniken
Kartenauswahl für Vorlagen-Mechaniken

Schutz gegen Mehrfachscans pro Tag (VALID_ONCE_PER_DAY)

Um versehentliches doppeltes Abstempeln oder Missbrauch an der Kasse zu verhindern, fügen Sie die Sekundärregel VALID_ONCE_PER_DAY hinzu:

  • Die Engine ermittelt die Zeitzone des Händlerstandorts über resolveCustomerTimeZone.
  • Scannt ein Teammitglied dieselbe Kundenkarte am selben Kalendertag ein zweites Mal, liefert der zweite Scan eine informative Warnung (ALREADY_SCANNED_TODAY), ohne einen unberechtigten zweiten Stempel hinzuzufügen.

Sperrbildschirm-Updates in Echtzeit

Sobald ein Stempel gutgeschrieben oder eingelöst wird:

  • Passinstance sendet eine stille APNs-Benachrichtigung an das iPhone der Kundin oder des Kunden.
  • Apple Wallet aktualisiert die visuelle Stempelgrafik und blendet einen Sperrbildschirm-Hinweis ein: „Sie haben einen Stempel erhalten! Sie haben jetzt 5 von 8 Stempeln.“
  • Google Wallet aktualisiert das Live-Karten-Widget und zeigt auf Android eine Benachrichtigung an.

Wichtig: Dynamische Stempelkarten-Strip-Grafiken werden von der Passinstance-Grafik-Engine automatisch in Retina-Auflösungen (@1x, @2x, @3x) gerendert und garantieren gestochen scharfe Stempelmarken auf hochauflösenden Smartphone-Displays.

Lesen Sie unsere vollständige Übersicht zu Digitalen Stempelkarten, entdecken Sie Restaurants & Cafés oder sehen Sie sich den Leitfaden zu Stempelsammelregeln an.

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.