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 (bv. een transactie of een admin-gebruiker)
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

Heb je het vervallen van punten aangezet, dan houdt Puntjes verdiende punten bij in batches. 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

Punten gaan altijd eerst uit de oudste batch (FIFO). Vervalt een batch, 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)
2. Elke keer dat een klant punten verdient, komt er een batch bij met expires_at op de verdiendatum plus dat aantal maanden
3. Wisselt een klant punten in, of pas je het saldo aan, dan gaan de oudste batches er eerst af
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, een negatief bedrag haalt ze eraf. 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.