Loyalty API

Erstelle und verwalte Treueprogramme (Stempel, Punkte, Cashback, Stufen) für deine Kunden. Treueprogramme erscheinen automatisch als Karte im Store-Profil der BEEP!-App und können von Endkunden beigetreten werden.

Create and manage loyalty programs (stamps, points, cashback, tiers) for your customers. Loyalty programs automatically appear as a card in the store profile in the BEEP! app and can be joined by end users.

Loyalty-Endpoints erfordern mindestens das GO-Paket. Erweiterte Features (Multi-Programm, benutzerdefinierte Belohnungen) erfordern GROW oder PRIME.Loyalty endpoints require at least the GO package. Advanced features (multi-program, custom rewards) require GROW or PRIME.

ProgrammtypenProgram Types: stamps (Stempelkarte), points (Punkteprogramm), cashback (Cashback), tier (Stufen-System)

POST /api/v1/createLoyaltyProgram

Erstellt ein neues Treueprogramm für einen Store. Das Programm wird nach Aktivierung automatisch im Store-Profil der BEEP!-App angezeigt.

Creates a new loyalty program for a store. Once activated, the program is automatically displayed in the store profile in the BEEP! app.

Parameter	TypType	PflichtRequired	BeschreibungDescription
`storeId`	string	JaYes	Store-IDStore ID
`programName`	string	JaYes	Name des TreueprogrammsLoyalty program name
`programType`	string	JaYes	`"stamps"` \| `"points"` \| `"cashback"` \| `"tier"`
`description`	string	Nein	Kurze BeschreibungShort description
`rules`	object	JaYes	Typ-spezifische Regeln (siehe unten)Type-specific rules (see below)
`rewards`	object[]	Nein	Liste der BelohnungenList of rewards
`branding`	object	Nein	Branding-Einstellungen (Farbe, Logo)Branding settings (color, logo)
`earningMethods`	string[]	Nein	Wie Kunden Punkte verdienen: `"qr_checkin"` \| `"store_checkin"` \| `"scan_and_go"` \| `"click_collect"`. Default: `["qr_checkin","store_checkin"]`How customers earn points: `"qr_checkin"` \| `"store_checkin"` \| `"scan_and_go"` \| `"click_collect"`. Default: `["qr_checkin","store_checkin"]`
`isActive`	boolean	Nein	Sofort aktivieren? Default: `false`Activate immediately? Default: `false`

Regel-Schemata nach TypRule schemas by type

stamps { "requiredStamps": 10, "stampsPerPurchase": 1, "pointsPerCheckin": 1 }

points { "pointsPerEuro": 10, "minimumPurchase": 5.0, "pointsPerCheckin": 5 }

cashback { "cashbackPercentage": 3, "maxCashbackPerTransaction": 5.0 }

tier

{ "pointsPerEuro": 10, "pointsPerCheckin": 5, "tiers": [{ "name": "Bronze", "minPoints": 0 }, { "name": "Silber", "minPoints": 500 }, { "name": "Gold", "minPoints": 1500 }] }

pointsPerCheckin: Punkte/Stempel pro QR- oder GPS-Check-in (unabhängig vom Einkaufsbetrag). Falls nicht gesetzt, wird stampsPerPurchase als Fallback verwendet (Standard: 1).pointsPerCheckin: Points/stamps awarded per QR or GPS check-in (independent of purchase amount). Falls back to stampsPerPurchase if not set (default: 1).

Response (200 OK)

200 OK

{ "success": true, "programId": "lp_abc123", "storeId": "store_a", "createdAt": "2026-03-03T12:00:00.000Z" }

POST /api/v1/enrollInLoyaltyProgram

Meldet einen Benutzer für ein Treueprogramm an.

Enrolls a user in a loyalty program.

Parameter	Typ	PflichtRequired	BeschreibungDescription
`programId`	string	JaYes	ID des TreueprogrammsLoyalty program ID
`userId`	string	JaYes	Benutzer-IDUser ID

POST /api/v1/addLoyaltyPoints

Fügt Punkte/Stempel zum Account eines Benutzers hinzu. Wird typischerweise nach einer Transaktion aufgerufen.

Adds points/stamps to a user's loyalty account. Typically called after a transaction.

Parameter	Typ	PflichtRequired	BeschreibungDescription
`programId`	string	JaYes	ID des TreueprogrammsLoyalty program ID
`userId`	string	JaYes	Benutzer-IDUser ID
`points`	number	JaYes	Anzahl der Punkte / Stempel / Cashback-BetragNumber of points / stamps / cashback amount
`transactionId`	string	Nein	Referenz zur TransaktionTransaction reference
`purchaseAmount`	number	Nein	Einkaufsbetrag in EUR (für automatische Berechnung)Purchase amount in EUR (for automatic calculation)

POST /api/v1/redeemLoyaltyPoints

Löst Punkte/Stempel eines Benutzers ein. Kann einen Reward-Code oder einen Rabatt-Gutschein zurückgeben.

Redeems a user's points/stamps. Can return a reward code or discount voucher.

Parameter	Typ	PflichtRequired	BeschreibungDescription
`programId`	string	JaYes	ID des TreueprogrammsLoyalty program ID
`userId`	string	JaYes	Benutzer-IDUser ID
`points`	number	JaYes	Einzulösende PunktePoints to redeem
`rewardDescription`	string	JaYes	Beschreibung der einzulösenden Belohnung (z.B. "10% Rabatt"). Wird in der Transaktionshistorie des Kunden angezeigt.Description of the reward being redeemed (e.g. "10% Discount"). Shown in the customer's transaction history.
`rewardId`	string	Nein	Spezifische Belohnung einlösenRedeem specific reward

Atomare Transaktionssicherheit: Jede Einlösung wird als atomare Datenbank-Transaktion ausgeführt. Wenn der Kontostand zum Zeitpunkt des Schreibens nicht ausreicht (z.B. bei parallelen Requests), wird die Transaktion automatisch abgebrochen. Doppelabzug ist nicht möglich.Atomic transaction safety: Every redemption is executed as an atomic database transaction. If the balance is insufficient at write time (e.g. concurrent requests), the transaction is automatically aborted. Double-deduction is not possible.

POST /api/v1/getLoyaltyAnalytics

Gibt Analyse-Daten für ein Treueprogramm zurück: Mitglieder, vergebene Punkte, Einlösungen, Einlösungsrate.

Returns analytics data for a loyalty program: members, issued points, redemptions, redemption rate.

Parameter	Typ	PflichtRequired	BeschreibungDescription
`programId`	string	JaYes	ID des TreueprogrammsLoyalty program ID

Response (200 OK)

200 OK

{ "success": true, "totalMembers": 142, "totalPointsIssued": 28400, "totalRedemptions": 87, "redemptionRate": 61.3, "earnedThisMonth": 4200, "redeemedThisMonth": 1800 }

GET /api/v1/getCustomerBalance

Gibt den Kontostand, Tier-Status und letzte Transaktionen eines Kunden für ein bestimmtes Treueprogramm zurück.

Returns a customer's balance, tier status, and recent transactions for a specific loyalty program.

Parameter	Typ	PflichtRequired	BeschreibungDescription
`userId`	string	JaYes	Benutzer-IDUser ID
`programId`	string	JaYes	Treueprogramm-IDLoyalty program ID

Response (200 OK)

200 OK

{ "currentBalance": 142, "totalEarned": 280, "totalRedeemed": 138, "currentTier": "Silber", "isActive": true, "recentTransactions": [...] }

POST /api/v1/updateLoyaltyProgram

Aktualisiert ein bestehendes Treueprogramm. Änderungen werden sowohl in der Store-Subcollection als auch in der Top-Level-Collection gespiegelt.

Updates an existing loyalty program. Changes are mirrored to both the store subcollection and the top-level collection.

Parameter	TypType	PflichtRequired	BeschreibungDescription
`programId`	string	JaYes	ID des TreueprogrammsLoyalty program ID
`programName`	string	Nein	Neuer Programmname (max 100 Zeichen)New program name (max 100 chars)
`description`	string	Nein	Neue BeschreibungNew description
`rules`	object	Nein	Aktualisierte RegelnUpdated rules
`branding`	object	Nein	Branding-Einstellungen (Farbe, Logo)Branding settings (color, logo)
`isActive`	boolean	Nein	Aktivierungsstatus ändernChange activation status

GET /api/v1/getLoyaltyProgram

Gibt ein einzelnes Treueprogramm anhand seiner ID zurück.

Returns a single loyalty program by its ID.

Parameter	TypType	PflichtRequired	BeschreibungDescription
`programId`	string	JaYes (Query)	ID des TreueprogrammsLoyalty program ID

GET /api/v1/getLoyaltyPrograms

Gibt alle Treueprogramme eines Stores zurück.

Returns all loyalty programs for a store.

Parameter	TypType	PflichtRequired	BeschreibungDescription
`storeId`	string	JaYes (Query)	Store-IDStore ID

POST /api/v1/getLoyaltyWebhookEvents

Registriert oder ruft Webhook-Konfigurationen für Loyalty-Events ab. Webhooks ermöglichen Echtzeit-Benachrichtigungen zu Punktevergabe, Einlösungen und Tier-Upgrades.

Registers or retrieves webhook configurations for loyalty events. Webhooks enable real-time notifications for points earned, redemptions, and tier upgrades.

Parameter	Typ	PflichtRequired	BeschreibungDescription
`storeId`	string	JaYes	Store-IDStore ID
`url`	string	JaYes	Webhook-URL (HTTPS)Webhook URL (HTTPS)
`events`	string[]	JaYes	`loyalty.points_earned`, `loyalty.points_redeemed`, `loyalty.tier_changed`, `loyalty.enrollment`, `loyalty.reward_unlocked`, `loyalty.checkin_earned`, `loyalty.qr_earned`
`secret`	string	Nein	HMAC-Secret für Signatur-VerifizierungHMAC secret for signature verification

In der Sandbox werden Treueprogramme nicht tatsächlich erstellt. Die Response enthält immer "_sandbox": true und Mock-Daten.In sandbox mode, loyalty programs are not actually created. The response always contains "_sandbox": true and mock data.