Skip to content
Helpcentrum-gids
3 min leestijdGecontroleerd 2026-11-16

Belonings- & loyaliteitsprogramma's

Ontwerp meerlaagse punten- en tierprogramma's met spaarregels, niveau-upgrades en pushberichten.

In deze gids

Overzicht

In tegenstelling tot stempelkaarten met een vaste drempel modelleren Belonings- & loyaliteitsprogramma's doorlopende puntenopbouw en voortgang over meerdere niveaus (bijv. Brons -> Zilver -> Goud -> Platina). Passinstance biedt een uitgebreide loyaliteitsengine met dynamische regels voor punten per besteding, automatische niveauevaluatie, API's voor het inwisselen van beloningen en realtime pushupdates naar wallets.

Backendarchitectuur & loyaliteitsengine

Loyaliteitsprogramma's combineren continue saldobewaking met gestructureerde niveaudefinities in het Passinstance database-schema:

  • Pastype (pass type): storeCard (toont het actieve puntensaldo in prominente primaire zones).
  • Catalogus-demoblauwdruk: retail-loyalty.
  • Mechaniektype (mechanic type): LOYALTY_PROGRAM.
  • Belangrijkste loyaliteitsmodellen:

- Tier: Configureert drempelvereisten (bijv. 500 punten voor Zilver, 1.500 punten voor Goud), niveauvoordelen, aangepaste visuele kleuren en specifieke niveaubadge-afbeeldingen. - BalanceChange: Onveranderlijk transactiegrootboek dat elke puntentoekenning, inwisseling en handmatige aanpassing vastlegt.

SYSTEEMARCHITECTUUR
INTERACTIEVE ARCHITECTUUR
PUNTENOPBOUW & NIVEAU-UPGRADE
DEELNEMENDE SYSTEEMACTOREN
P1 POS / E-commerce aankoop
P2 Passinstance Core API
P3 Tier Progression Engine
P4 Klant Wallet-pas
STAP CTX KONTEXT Aankoop: € 120120 pnt
STAP 1 VERZOEK / ACTIE POST/api/v1/passes/:id/use
STAP 2 VERZOEK / ACTIE Saldo bijwerken
›
{ action: "INCREMENT", value }
›
(huidig + stap afgekapt)
STAP 3 VERZOEK / ACTIE Evalueer niveaus
›
(Drempel overschreden:
›
ZilverGoud)
STAP 4 ANTWOORD Niveau verhoogd
STAP 5 VERZOEK / ACTIE Stille APNs-push
STAP 6 ANTWOORD 200 OK (Nieuw niveau)
›
& Google REST PATCH | (Kaart schakelt naar Goud
›
Melding op scherm:
›
"Geüpgraded naar Goud!")

Engine voor puntenopbouw & niveauvoortgang

Pass Mechanics Engine en Tier Progression Engine voeren de loyaliteitsregels uit:

1. Berekening van puntenopbouw

Wanneer een aankoop of bezoek plaatsvindt:

  • De puntenstap gebruikt standaard defaultChangeValue (canoniek), met config.pointsPerScan of 1 als terugvalwaarde.
  • Voor POS- en e-commerce-integraties worden punten dynamisch berekend op basis van het aankoopbedrag:
TEXT
earnedPoints = floor(purchaseTotal * pointsMultiplier)
  newBalance = clamp(currentBalance + earnedPoints, minimumValue, maximumValue)
  • Als autoResetAtMaximum: true of config.onCap === "reset" is ingesteld, wordt het puntensaldo teruggezet naar resetTargetValue (of het beginsaldo) zodra maximumValue wordt bereikt.

2. Geautomatiseerde niveau-upgrades (Tier Progression Engine)

Na elke saldowijziging toetst Tier Progression Engine het cumulatieve puntentotaal van het lid aan de actieve niveaudrempels:

  • Als een grens wordt overschreden, promoveert de service het lid naar het hogere niveau.
  • De visuele kaartstijl wordt automatisch bijgewerkt (achtergrondkleuren, koptekstlabels en niveaubadge-iconen worden aangepast).
  • Er worden direct een stille APNs-push en een Google Wallet REST-update verstuurd, waarmee de klant op het toegangsscherm een native melding ontvangt: "Gefeliciteerd! U heeft het Goud-niveau bereikt."

API voor beloningsinwisseling

Wanneer een klant punten inwisselt voor korting, gratis artikelen of merchandise in de winkel of online:

HTTP-verzoek

POST /api/v1/mechanics/redeem
Headers
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-respons (200 OK)

JSON
{
  "success": true,
  "newBalance": 240,
  "newBalanceDecimal": "240",
  "message": "Reward redeemed successfully"
}

Synchronisatie tussen e-commerce & meerdere kanalen

Koppel fysieke kassa's en online webshops om één uniform klantgrootboek bij te houden (transaction type: EARN, REDEEM, ADJUST, REFUND, TRANSFER, BONUS, PENALTY, SCAN, API, ADJUSTMENT):

  • Shopware 6 / Shopify-connectors: Ontvang online bestelwebhooks (/api/v1/automations/webhooks/shopify/:customerId, /api/v1/automations/webhooks/woocommerce/:customerId, of Shopware-plug-inwebhooks) en schrijf punten automatisch bij op klantpassen die op externalId overeenkomen.
  • Canonieke Pass Use API (POST /api/v1/passes/:id/use): Aanbevolen programmatisch endpoint voor saldo-/puntenmutaties voor ERP's, apps en backendservices (met scanner-sleutel-tegenhanger POST /api/v1/scans/pass/:passId/use). De verouderde mechaniekgebeurtenis-inname (POST /api/v1/mechanics/:mechanicId/events) blijft ondersteund voor achterwaartse compatibiliteit, maar is afgeraden voor nieuwe integraties.

Belangrijk: Configureer changeMessage: "Puntensaldo bijgewerkt naar %@" op uw primaire puntenveld in de sjablooneditor. Zodra punten worden verdiend of afgeschreven, toont het toegangsscherm van de klant onmiddellijk het nieuwe saldo.

Lees meer over onze Loyaliteitsoplossing, verken Klantenkaarten of bekijk de Gids voor loyaliteitsvoortgangsregels.

Klaar om uw eerste kaartprogramma te lanceren?

Maak uw workspace aan, configureer uw sjabloon en test een echte kaart in Apple Wallet en Google Wallet voordat u opschaalt.