Wallets & Punten

Elke klant heeft één wallet: daarin staat het saldo aan loyaliteitspunten. Achter die wallet zit een append-only grootboek: elke puntbeweging komt erbij, en er verdwijnt nooit iets. Zo kun je van elk saldo nagaan waar het vandaan komt.

---

Walletoverzicht

Veld	Beschrijving
id	Uniek wallet-ID
customer_id	De klant bij wie deze wallet hoort
balance	Huidig puntensaldo (integer)
expiring_soon	Punten die binnenkort vervallen

Zodra je een klant registreert, maakt Puntjes de wallet aan. Elke klant heeft er precies één.

---

Grootboekregels

Het grootboek is een onveranderlijk, append-only register van elke puntbeweging. Elke grootboekregel bevat:

Veld	Beschrijving
type	Het soort beweging: earn, adjust, redeem of expire
amount	Signed integer: positief voor bijschrijvingen, negatief voor afschrijvingen
running_balance	Het walletsaldo na deze regel
reason	Toelichting in gewone taal
causer_type	Het soort veroorzaker: een transactie, een admin-gebruiker of een API-client
causer_id	Het ID van die veroorzaker
transaction_id	De gekoppelde transactie (bij earn-regels)
created_at	Tijdstempel van de regel

Soorten grootboekregels

Type	Richting	Veroorzaakt door
earn	Positief	Er is een transactie ingediend. De punten volgen uit je verdienregels
adjust	Positief of negatief	Een admin of de API past het saldo met de hand aan
redeem	Negatief	De klant wisselt een beloning in
expire	Negatief	Punten vervallen volgens het vervalbeleid dat je instelt

---

Puntbatches en vervaltermijn

Elke keer dat een klant punten spaart of je met de hand punten bijtelt, komt er een batch bij. Staat het vervallen van punten aan en hoort het bij je plan, dan krijgt die batch een vervaldatum. Anders vervalt ze nooit. Zet je het vervallen uit, of ga je naar een plan zonder vervallen, dan geldt dat alleen voor nieuwe batches: een batch die al een vervaldatum heeft, houdt die en vervalt nog op die dag. Elke batch legt vast:

Veld	Beschrijving
amount	De punten in deze batch
consumed	Wat er al uit deze batch is gebruikt
expires_at	Wanneer de rest van deze batch vervalt

Bij een inwisseling, en als je met de hand punten afhaalt, gaan de punten eerst uit de batch die het eerst vervalt, en een batch zonder vervaldatum komt als laatste aan de beurt. Dat is niet hetzelfde als de volgorde waarin je klant ze spaarde: je kunt expiration_months aanpassen of het vervallen uitzetten wanneer je wil, dus een batch van vroeger kan later vervallen dan een batch van daarna. Door eerst de punten te gebruiken die het snelst vervallen, verliest je klant geen punten die de inwisseling had kunnen opgebruiken. Vervalt een batch toch, dan gaan de punten die er nog in zitten van de wallet af, als een expire-regel in het grootboek.

Hoe punten vervallen

1. Je zet het vervallen van punten aan en stelt expiration_months in (bv. 12 maanden); het vervallen moet bij je plan horen
2. Elke keer dat een klant punten verdient of je er met de hand bijtelt terwijl het vervallen aanstaat en bij je plan hoort, komt er een batch bij met expires_at op die datum plus dat aantal maanden
3. Wisselt een klant punten in of haal je met de hand punten af, dan gaat de batch die het eerst vervalt er als eerste af. Zo haalt het vervallen alleen punten weg die de klant nog heeft
4. Een achtergrondtaak kijkt regelmatig welke batches vervallen zijn en boekt die af als expire

---

Handmatige aanpassingen

Een beheerder past een walletsaldo met de hand aan in het adminportaal of via de API. Zo'n aanpassing levert een nieuwe grootboekregel op met type adjust:

POST /api/v1/customers/{customer}/wallet/adjust

{
    "amount": 500,
    "reason": "Compensatie voor een serviceprobleem",
    "idempotency_key": "goodwill-2024-0042"
}

Een positief bedrag telt punten bij in een nieuwe batch, die net als gespaarde punten vervalt. Een negatief bedrag haalt ze eraf, uit de batch die het eerst vervalt. Dankzij de idempotency_key kun je de aanroep gerust opnieuw sturen: dezelfde sleutel voor dezelfde klant levert de oorspronkelijke grootboekregel op, en verplaatst het saldo geen tweede keer.

Zie Wallet-endpoints voor de volledige API-referentie.