Wallets & Points
Designing wallets, showing balances, expiring points and history to members, adjusting points safely and keeping other systems in step.
A wallet holds a member's units — points, stamps, miles. Campaigns add to it, rewards spend from it, and expiry takes units away. This page covers designing wallets, showing their state to members, adjusting units from your own tools, and keeping CRM in step.
For the Admin Panel side, see Wallet types and configuration and Unit transfers. For several brands with separate balances, see Multi-brand programmes and wallets.
Who does what
Admin Panel
Wallet types (code, unit names), expiry, pending method, limits; custom expiry and pending per campaign where needed
Integration layer
Reads balances, expiring units and history for the channels; makes manual adjustments with a stable externalTransferId
Website / app
Shows balance, pending and expiring units, and history
Support / back office
Requests goodwill credits and corrections through the integration layer or the Admin Panel
CRM / marketing automation
Keeps a copy of the balance from webhooks; sends expiry reminders
Design decisions
How many wallets
One, or one per currency of value (brand, partner, stamps vs points)
One wallet unless balances must stay separate. Every extra wallet needs its own campaigns, rewards and UI.
Expiry
None, fixed period after earning, fixed date
Agree it with legal and finance before launch; changing it later affects units already earned.
Pending
Available at once, or locked for a period
Lock units from purchases for the return window, so returned orders can't be spent first.
Where the balance is read
Live from Open Loyalty, or from a copy in CRM
Live from Open Loyalty for anything the member sees; CRM's copy (from webhooks) for messaging and segmentation.
Who adjusts units
Admin Panel only, or also your support tool
Admin Panel for occasional fixes; the API with externalTransferId if adjustments come from a ticketing or back-office tool.
Cost of a unit
Not set, or a cost per unit per wallet
Set the cost per unit on every wallet that campaigns award, with finance's value of a point — Product Analytics shows the loyalty cost as unknown without it. Corrections recalculate history.
Recommended flow
Show history
GET /api/{storeCode}/member/{member}/history?walletType:code={wallet}&type[in]=PointsWereAdded,PointsWereSpent,PointsWereExpired&_orderBy[createdAt]=desc&_page=1&_itemsOnPage=10 returns one line per movement with the units, a comment (campaign or reward name) and the balance after it. See the timeline event types.
Adjust units
POST /api/{storeCode}/points/add with the member, walletCode, points, a comment and an externalTransferId taken from your ticket or batch (e.g. TICKET-4711). It's unique per tenant: a retry gets 400 "Unit transfer with such externalTransferId already exists" — treat it as already added. To take units away, use spend; to hold them, block. See Managing unit transfers.
Sequence diagrams


Go-live checklist
Admin Panel
Integration layer
Channels and CRM
Validation
Key endpoints
GET /api/{storeCode}/member/{member}/wallet— Get member's wallets detailsGET /api/{storeCode}/points— Get units transfers listGET /api/{storeCode}/member/{member}/history— Check member's activity historyPOST /api/{storeCode}/points/add— Add an units transferPOST /api/{storeCode}/points/spend— Spend unitsPOST /api/{storeCode}/points/block— Block unitsPOST /api/{storeCode}/points/{transfer}/cancel— Cancel units transfer
Webhooks: WalletBalanceUpdated, PointsWillExpire, UnitsTransferWasAdded
Last updated
Was this helpful?

