# How loyalty points work

> Which events earn points, how earn and redeem rules are applied, when points expire or are reversed on refund, how shoppers reach their loyalty page, and where loyalty shows up elsewhere in Releva.

Releva’s loyalty program turns orders into points and points into coupon codes. You set the rules under **Data Platform › Loyalty**; Releva grants the points as events arrive, keeps a balance per profile, and hosts the page where shoppers see their points and buy rewards. This page explains the mechanics. For the clicks, read [Set up your loyalty program](https://releva.ai/documentation/guides/loyalty/set-up-your-loyalty-program/) and [Customize your loyalty page](https://releva.ai/documentation/guides/loyalty/customize-your-loyalty-page/).

## The pieces

| Piece                | Where                                                            | What it does                                                                                             |
| -------------------- | ---------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| **Earn rule**        | **Loyalty › Earn Points**                                        | Says which event grants points, how many, and for how long they are valid.                               |
| **Redeem rule**      | **Loyalty › Redeem Points**                                      | Offers a reward: a title, a description, a point cost, and the Dynamic Coupons list the codes come from. |
| **Balance**          | per profile; shown as **Loyalty points** on the profile overview | The sum of the profile’s unexpired points, including profiles merged with it, never below 0.             |
| **Loyalty page**     | hosted by Releva, personal link per profile                      | Shows the balance and the rewards; buying a reward returns a coupon code.                                |
| **Display Settings** | **Loyalty › Display Settings**                                   | Layout, colours, typography and texts of the loyalty page.                                               |

## Which events earn points

Releva checks every incoming event against your earn rules as it is ingested. A rule matches when:

* the event’s action is the rule’s **Event** (for example **Cart Checkout Completed**), and
* the rule has no **Tags**, or the event carries one of them, and
* the event has an order value above 0 in your shop currency, and
* for **Value-based** rules, the value is at least **Min Value**.

The third condition applies to both rule types. Today only events that carry a value earn points: orders, and custom events sent with a `value`. An **Event-based** rule on **Registered** or **Subscribed** matches nothing, so welcome points for a subscription are not possible yet. Events tagged `backfill` (imported history) never earn points either.

Points are rounded to whole numbers:

| Type            | Points granted                                                                                 |
| --------------- | ---------------------------------------------------------------------------------------------- |
| **Value-based** | points per 1 EUR × order total in your shop currency (orders below **Min Value** earn nothing) |
| **Event-based** | the fixed number of points per event                                                           |

Rules are cached for about 10 seconds, so a new or changed rule applies to events that arrive from then on. Earlier events are not re-scored, and deleting a rule does not remove points it already granted. Each grant writes a **Loyalty Points Earned** event on the profile, which you can see under **Data Platform › Events** and use in segments.

## When points expire

Every grant has its own expiry, set by the rule:

* **Duration**: the points expire **Expire After** days after the order (not after the grant).
* **Calendar**: the points expire on 1 January (UTC) of the year after the order. Points for an order in December last only a few weeks.

Expired points leave the balance automatically. There is no “never expires” option; use **Duration** with a large number of days instead.

## Refunds

When a refund reaches Releva (`POST /api/v0/refunds` or your platform connector), rules with **Reverse on refund** on take points back from the order that earned them:

* **Value-based** grants are reduced in proportion to the refunded amount (refunded amount divided by the order total, at most 100%).
* **Event-based** grants are taken back in full on any refund.

Each reversal is recorded as a `loyaltyRefund` event on the profile with the number of points taken back.

Only grants from order events are reversed, and only while they have not expired. Points already spent cannot be reversed, so the balance stops at 0. Turn **Reverse on refund** off for grants that should survive a refund, such as a fixed promo bonus; the **Earn Points** table marks them **POINTS KEPT**. See [Check that a refund was recorded](https://releva.ai/documentation/guides/orders/check-that-a-refund-was-recorded/).

## Redeeming

A reward is listed on the loyalty page while its coupon list still has unused codes; it does not depend on the shopper’s balance. When a shopper buys a reward:

1. Releva checks the balance against the **Point cost** and claims one unused code from the list.
2. The cost is taken from the soonest-expiring points first.
3. A redemption event (`loyaltyPurchase`) is recorded on the profile, counted as **Points Redeemed** and **Coupons Purchased** at the top of the Loyalty page, and the code is shown to the shopper.

The three steps run as one transaction, so two clicks cannot spend the same points twice. Codes are one-time, as in any Dynamic Coupons list: [How dynamic coupons work](https://releva.ai/documentation/learn/dynamic-coupons/how-dynamic-coupons-work/). Deleting a coupon list also deletes the redeem rules that use it.

## How shoppers reach their page

The loyalty page is personal: its link identifies the profile, and anyone with the link can see the balance and spend the points. Releva creates the link for you in messages: add the `{{loyaltyLink}}` merge tag to an email, SMS, Viber or WhatsApp message. In the email editor, the link menu offers it as the loyalty program link. Each shopper gets their own link.

Links do not expire. The page picks its language from the embedding site, the browser or the shop locale, and falls back to the **Default** texts for languages without a translation.

## The statistics at the top of the Loyalty page

For the selected period (default: last 30 days): **Points Earned** is the sum of points granted, **Points Redeemed** the sum of points spent, and **Coupons Purchased** the number of rewards bought. Ignore the percentage next to **Points Redeemed**; it is not a meaningful ratio today.

## Next steps

* [Set up your loyalty program](https://releva.ai/documentation/guides/loyalty/set-up-your-loyalty-program/): Create an earn rule and a redeem rule so shoppers collect and spend points.
* [Customize your loyalty page](https://releva.ai/documentation/guides/loyalty/customize-your-loyalty-page/): Change the logo, colours and wording shoppers see, and check them in the live preview.
* [Upload a list of coupon codes](https://releva.ai/documentation/guides/dynamic-coupons/upload-a-list-of-coupon-codes/): Create the coupon list a reward hands its codes out from.
* [How events get into Releva](https://releva.ai/documentation/learn/events/how-events-get-into-releva/): Learn how the order events that earn points reach Releva.