> For the complete documentation index, see [llms.txt](https://help.openloyalty.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.openloyalty.io/implementation-guide/module-checklists/wallets-and-points.md).

# 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](https://help.openloyalty.io/members-and-activity/wallets/wallet-types-and-configuration) and [Unit transfers](https://help.openloyalty.io/members-and-activity/wallets/unit-transfers). For several brands with separate balances, see [Multi-brand programmes and wallets](https://help.openloyalty.io/implementation-guide/plan-and-foundations/multi-brand-and-wallets.md).

## Who does what

| Area                           | Responsibility                                                                                                                                                                                                       |
| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Admin Panel**                | Wallet types (code, unit names), expiry, pending method, limits; [custom expiry and pending](https://help.openloyalty.io/campaigns/campaigns/custom-units-expiration-and-pending-settings) 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](https://help.openloyalty.io/members-and-activity/wallets/wallet-types-and-configuration#cost-per-unit) on every wallet that campaigns award, with finance's value of a point — [Product Analytics](https://help.openloyalty.io/integrations-and-data-exchange/product-catalog/product-analytics) shows the loyalty cost as unknown without it. Corrections recalculate history. |

## Recommended flow

{% stepper %}
{% step %}

### 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.
{% endstep %}

{% step %}

### 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.
{% endstep %}

{% step %}

### 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.
{% endstep %}

{% step %}

### 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](https://help.openloyalty.io/members-and-activity/members/member-list/single-member-view/timeline).
{% endstep %}

{% step %}

### 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](https://help.openloyalty.io/members-and-activity/wallets/unit-transfers/managing-unit-transfers).
{% endstep %}

{% step %}

### Keep CRM in step

Subscribe to `WalletBalanceUpdated` (balance before and after, per wallet) and `PointsWillExpire` (for reminders).
{% endstep %}
{% endstepper %}

## Sequence diagrams

<figure><img src="https://226878483-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZ4Fuoa1PTF0DrNTgjzJu%2Fuploads%2Fgit-blob-73f2b29409c14b0842b8148a453e918e8b227538%2Fig-wallets-reading.png?alt=media" alt="A member opens the loyalty dashboard. The integration layer reads, in parallel, the member&#x27;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." width="676"><figcaption><p>Balance, expiring units and history for a dashboard</p></figcaption></figure>

<figure><img src="https://226878483-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZ4Fuoa1PTF0DrNTgjzJu%2Fuploads%2Fgit-blob-4aa2fc7cab4de8b5f5e1e2d6ad0bcc0663dc8e59%2Fig-wallets-adjust-and-sync.png?alt=media" alt="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." width="655"><figcaption><p>Manual adjustment and keeping CRM in step</p></figcaption></figure>

{% hint style="info" %}
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](https://help.openloyalty.io/technical-guide/api-fundamentals/scroll-mechanism-for-pages) instead of high page numbers.
{% endhint %}

## Go-live checklist

### Admin Panel

* [ ] Wallet codes, unit names, expiry and pending method match the programme terms.
* [ ] Campaigns that need a different expiry or pending period use the campaign-level settings.

### Integration layer

* [ ] Balance shown to members is `activeUnits`, read live from Open Loyalty.
* [ ] Pending units (`lockedUnits`) and expiring units are shown where members expect them.
* [ ] History queries filter by wallet and type and always set paging and ordering.
* [ ] Every API adjustment carries an `externalTransferId`, and the duplicate `400` is treated as success.

### Channels and CRM

* [ ] CRM updates the balance from `WalletBalanceUpdated`.
* [ ] Expiry reminders are triggered from `PointsWillExpire`.

### Validation

* [ ] Earn, spend and expiry each appear in history with the right sign and comment.
* [ ] A purchase with a pending period shows as pending, then becomes spendable.
* [ ] A retried adjustment adds units once.
* [ ] CRM shows the same balance as the website after earn and spend.

## Key endpoints

* `GET /api/{storeCode}/member/{member}/wallet` — [Get member's wallets details](https://help.openloyalty.io/api-reference/wallet/get-members-wallets-details)
* `GET /api/{storeCode}/points` — [Get units transfers list](https://help.openloyalty.io/api-reference/points/get-units-transfers-list)
* `GET /api/{storeCode}/member/{member}/history` — [Check member's activity history](https://help.openloyalty.io/api-reference/member/check-members-activity-history)
* `POST /api/{storeCode}/points/add` — [Add an units transfer](https://help.openloyalty.io/api-reference/points/add-an-units-transfer)
* `POST /api/{storeCode}/points/spend` — [Spend units](https://help.openloyalty.io/api-reference/points/spend-units)
* `POST /api/{storeCode}/points/block` — [Block units](https://help.openloyalty.io/api-reference/points/block-units)
* `POST /api/{storeCode}/points/{transfer}/cancel` — [Cancel units transfer](https://help.openloyalty.io/api-reference/points/cancel-units-transfer)

**Webhooks:** [WalletBalanceUpdated](https://apidocs.openloyalty.io/#tag/Webhook-event/operation/WalletBalanceUpdated), [PointsWillExpire](https://apidocs.openloyalty.io/#tag/Webhook-event/operation/PointsWillExpire), [UnitsTransferWasAdded](https://apidocs.openloyalty.io/#tag/Webhook-event/operation/UnitsTransferWasAdded)

{% hint style="warning" %}
**Common pitfalls**

* Showing `earnedUnits` as the balance: it includes units already spent or expired.
* Caching the balance in the channel: members see stale numbers after earning or redeeming.
* Adjusting units without `externalTransferId`: a retried request adds them twice.
* Changing the expiry rule after launch without planning what happens to units already earned.
  {% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://help.openloyalty.io/implementation-guide/module-checklists/wallets-and-points.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
