🔗Stamply API

Kurzer Integrations-Guide für Entwickler & Integratoren

Die Stamply API ermöglicht Eigenintegrationen um Loyalty-Aktionen programmgesteuert auszuführen.

API Reference (OpenAPI / ReDoc): Alle Endpoints, Request/Response-Schemas, Parameter und Beispiele findest du hier:

ReDocdocs.stamply.ch

Authentifizierung (API Key)

Alle Requests an die Stamply API müssen mit einem API Key authentifiziert werden.

So verwendest du den API Key

Der API Key wird als HTTP Header mitgesendet, zum Beispiel:

GET /something HTTP/1.1
X-API-Key: abcdef12345

API Key finden

1. In der Stamply Plattform Einstellungen öffnen

2. Tab Integrations wählen

3. Unter API den API Key kopieren

Rate Limit

Aktuelles Limit:

• 10 Requests / Sekunde (≈ 600 Requests / Minute)

• Bei Überschreitung: HTTP 429 – Too Many Requests

• Dies bedeutet, dass das Limit erreicht wurde und der Client die Anfragefrequenz verringern muss.

Zentrale Konzepte

Die Stamply API unterscheidet zwischen Kartentyp (Card Type ID) und teilweise zusätzlich der Mechanik (z. B. Visit, Spend, Points). Nicht jede Methode funktioniert für jeden Kartentyp. Die folgende Übersicht zeigt, was zulässig ist.

Card Types (IDs)

Card Type	ID
Stamp	0
Cashback	1
Multipass	2
Coupon	3
Discount	4
Gift	5
Membership	6
Reward	7

Methoden nach Kartentyp

Legende

• ✓ = grundsätzlich unterstützt

• ✓* = nur mit passender Mechanik / Einschränkung (siehe Hinweise unter der Tabelle)

Methode	[0] Stamp	[1] Cashback	[2] Multipass	[3] Coupon	[4] Discount	[5] Gift	[6] Membership	[7] Reward
Add amount		✓
Subtract amount		✓
Add point		✓			✓	✓
Subtract point		✓			✓	✓
Add stamp	✓
Subtract stamp	✓
Add reward	✓
Subtract reward	✓
Add scores			✓					✓*
Subtract scores			✓					✓
Add visit	✓*		✓				✓*	✓*
Subtract visit			✓				✓*
Add purchase	✓*							✓*
Receive reward (by client)								✓
Redeem coupon				✓

Hinweise / Einschränkungen

• Add visit

  • Stamp (0) nur, wenn die Karte auf Visit-Mechanik basiert.

  • Reward (7) nur, wenn die Karte auf Visit-Mechanik basiert.

  • Membership (6) nur, wenn ohne Limits konfiguriert.

• Subtract visit

  • Membership (6) nur, wenn mit Limits konfiguriert.

• Add purchase

  • Stamp (0) nur, wenn die Karte auf Spend/Purchase-Mechanik basiert.

  • Reward (7) nur, wenn die Karte auf Spend/Purchase-Mechanik basiert.

• Add scores (Reward)

  • Reward (7) nur, wenn Mechanik-Typ “Points” ist.

Die konkreten Endpoints und Payloads findest du in der API Reference (ReDoc).

Häufigste POS-Methoden

• Stamp (0) + Visit Mechanik → Add visit

• Stamp (0) + Spend Mechanik → Add purchase

• Cashback (1) → Add/Subtract amount

---

Grundobjekte

Objektbereich	Typische Operationen
Customers	list / get / create / update / delete
Cards	list / issue (create for customer) / get / delete
Companies / Sub-Accounts	list / get / create / update / change tariff
Operations	list
Templates	list / get
Tariffs	list / get
Push (optional)	list / get / send

Spezialfall: Einlösen von Prämien gegen Kosten (Stempelkarten)

In der Scanner-App kannst du beim Einlösen einer Prämie deren Kosten manuell eingeben. Dieser Betrag wird zum LTV (Lifetime Value) des Kunden addiert.

Das gleiche Verhalten kannst du über die API mit der Methode Subtract reward from card erzielen.

Wenn du bei einer Reward-Redemption einen monetären Wert erfassen willst, wird dieser als purchaseSum übergeben und in den LTV eingerechnet.

Beispiel:

{
  "rewards": 1,
  "comment": "Reward redeemed",
  "purchaseSum": 10.5
}

• rewards → Anzahl Rewards, die abgezogen werden

• comment → optionaler Kommentar

• purchaseSum → monetärer Wert des eingelösten Rewards (für LTV)

Wichtig: Der Reward-Preis wird nicht automatisch aus den Karteneinstellungen übernommen. Wenn du den Wert tracken willst, musst du purchaseSum bei jedem Call explizit setzen.