For the complete documentation index, see llms.txt. This page is also available as Markdown.

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

Area
Responsibility

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

Decision
Options
Recommendation

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.

1

Configure (Admin Panel)

Create the wallet types with their codes, unit names, expiry and pending method. The code (e.g. points) is what the API filters on.

2

Show the balance

GET /api/{storeCode}/member/{member}/wallet returns each wallet with activeUnits (spendable), lockedUnits (pending), blockedUnits, spentUnits, expiredUnits and earnedUnits. Show activeUnits as the balance and lockedUnits as pending.

3

Show what's expiring

GET /api/{storeCode}/points?member:loyaltyCardNumber={id}&walletType:code={wallet}&type=adding&expiresAt[gte]={now}&expiresAt[lte]={now + 30 days} lists the transfers that expire in that window; sum their values.

4

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.

5

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.

6

Keep CRM in step

Subscribe to WalletBalanceUpdated (balance before and after, per wallet) and PointsWillExpire (for reminders).

Sequence diagrams

A member opens the loyalty dashboard. The integration layer reads, in parallel, the member's wallets with active, locked, spent and expired units; the units transfers that expire within 30 days, whose values it sums; and the member history filtered to points added, spent and expired, newest first. It returns the dashboard data to the channel.
Balance, expiring units and history for a dashboard
A support tool asks the integration layer to add points for a ticket. The integration layer calls points add with the wallet code, points, a comment and the ticket number as externalTransferId; a retry with the same ID returns 400 because it was already added. Open Loyalty sends WalletBalanceUpdated and PointsWillExpire webhooks, which the integration layer uses to update the balance in CRM and trigger expiry reminders.
Manual adjustment and keeping CRM in step

List calls always need _page, _itemsOnPage and _orderBy — don't rely on defaults. Use the comma form for type filters (type[in]=A,B). For deep lists, use the scroll mechanism instead of high page numbers.

Go-live checklist

Admin Panel

Integration layer

Channels and CRM

Validation

Key endpoints

Webhooks: WalletBalanceUpdated, PointsWillExpire, UnitsTransferWasAdded

Last updated

Was this helpful?