> For the complete documentation index, see [llms.txt](https://kbase.whitelabel-loyalty.com/developer/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://kbase.whitelabel-loyalty.com/developer/guides/integrate-with-pos/redeeming-points.md).
# Redeeming points
## Overview
This article outlines how to allow users to redeem loyalty points for a discount directly at checkout. It requires you to first create a [custom event type](https://kbase.whitelabel-loyalty.com/product/loyalty-engine/events/event-types#custom-event-types) corresponding to points redemptions, and a reactor which then deducts the points when an event of this type occurs.
***
## Pre-requisites
1. Setup a [custom event type](https://kbase.whitelabel-loyalty.com/product/loyalty-engine/events/event-types/creating-event-types), like `REDEEMED_POINTS`, and include `points` in the payload schema. You may optionally want to include data like transaction ID, store ID, cashier ID etc. in the payload too.
2. Setup a [reactor](https://kbase.whitelabel-loyalty.com/product/loyalty-engine/reactors/creating-reactors) which triggers on your custom event type, and adjust's a user's points balance by `$.points * -1`.
***
## Implementation steps
{% stepper %}
{% step %}
### Identify member
Retrieve the member ID via POS (QR code or manual input).
{% endstep %}
{% step %}
### Retrieve points balance
Call [**`GET /users/{id}/wallet`**](https://docs.whitelabel-loyalty.com/rewards#users-specific-user-wallet-get) to fetch the member’s points balance.
{% endstep %}
{% step %}
### Confirm redemption amount
* Ask the user how many points they want to redeem – ensure this does not exceed the number of points in their balance.
* Use the program’s points redemption rate to calculate the equivalent discount. You may choose to store the redemption rate as a [setting](https://docs.whitelabel-loyalty.com/rewards.html#settings-settings-collection-get), so it can be updated easily in the loyalty config at any time without the need for POS updates (for example a `key:value` pair of `pointsCurrencyValue:0.01` could indicate 1 point is worth 1 cent.)
{% endstep %}
{% step %}
### Report redemption
* Call [**`POST /events`**](https://docs.whitelabel-loyalty.com/rewards.html#events-events-collection-post) to report an event matching your custom event type for points redemptions, with the number of points being redeemed included in the payload.
* You may choose to fetch the member's points balance again immediately before reporting the event to ensure the points balance has not changed in the time it's taken the user to enter the number of points they want to redeem.
{% endstep %}
{% step %}
### Apply discount in POS
Deduct the calculated amount from the transaction total.
{% endstep %}
{% endstepper %}
***
## Important notes
* **Never include PII in redemption event payloads.**
* **Prevent over-redemption** – Ensure POS does not allow users to redeem more points than their balance (the Loyalty Engine itself **allows** negative balances – if a user has 500 points, and you report an event which results in them having 1000 points deducted, the event will be reported successfully and their new balance will be -500 points).
* **Deduct before payment** – Report the redemption before payment is completed to prevent multiple simultaneous redemptions in different locations.
* **Handle failed transactions** – If a transaction is canceled or voided after points have been deducted, report a compensating event (e.g., `POINTS_REFUND`) with the inverse value to restore the balance.
***
## FAQs
#### What happens if a user redeems points, but their transaction fails?
To handle transaction failures, setup another custom event type and reactor which is the reverse of the above instructions (e.g., `POINTS_REFUND`), and report that event when the failure occurs.
---
# 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 dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://kbase.whitelabel-loyalty.com/developer/guides/integrate-with-pos/redeeming-points.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
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.