---
title: 'Redemption policies'
description: 'How loyalty decides how much of the customer balance can be used on an order: which policies apply, the cap of each one, the aggregation mode and how policies compete.'
---

# Redemption policies

When an order asks for a redemption (for example, through [Reward by order](/docs/{lang}/api-reference/loyalty/checkout/reward-by-order)), loyalty has to decide **which** of the customer's cards are used and **how much** of each. This guide explains that decision step by step, with examples.

## Concepts

- **Card** (`rewardCard`) — each credit the customer earned (cashback, bonus, points). It has its own balance and expiry date.
- **Redemption policy** (also called **wallet**) — the set of rules that says **where** and **how much** of that balance can be used. Every card belongs to a policy; the card's `wallet` field is the policy id.

The campaign defines which policy its cards are created in. Two campaigns on the same policy create balance in the same wallet.

## Step 1 — Which policies apply to this order

A policy only takes part if **all** the conditions below are true:

| Condition | What is checked |
|---|---|
| Store | The order's store is linked to the policy. |
| Redemption enabled | The policy has redemption turned on. |
| Tags | The customer has every required tag and none of the excluded tags. |
| Tier | The customer's tier is among the allowed ones (or outside the excluded ones). |
| Dynamic minimum | If the policy requires a minimum purchase proportional to the balance (`minOrderRate`), the order must reach it. When it does not, the wallet is left out and the reason comes in `redeemable.blocked`. |

Cards of a policy that did not pass this step are not used, even with balance.

## Step 2 — The cap of each policy

Each policy calculates **the maximum discount it accepts on this order**, considering only the items it authorizes (allowed categories and collections, without the excluded collections):

- **Minimum / maximum value** (`minOrderTotal` / `maxOrderTotal`) — if the total of the authorized items falls outside the range, the policy grants no discount.
- **Limit** (`maxOrderRate`) — up to `1`, it is a percentage: `0.3` = up to 30% of the authorized items. Above `1`, it is a fixed amount in cents (see [Monetary values](/docs/{lang}/guides/monetary-values)): `5000` = up to $50.00. With no limit, the total of the authorized items applies.

The cap belongs to **the policy**: its cards, together, never go above it.

## Step 3 — Inside the policy: the aggregation mode

The policy's aggregation mode defines how **its own cards** combine:

| Mode | Behavior inside the policy |
|---|---|
| **Aggregate** (`aggregate`) | Adds up every card of the policy, up to the cap. |
| **Single** (`single`) | Uses **one** card only: the one that gives the largest discount. |
| **Mixed** (`mixed`) | Same as Aggregate. Kept for policies already configured this way. |

The mode used is the policy's **current** one. Changing the mode also applies to cards that already exist.

## Step 4 — Between policies: they compete, never add up

If the customer has balance in **more than one valid policy** for the order, the policies **compete with each other**. The order uses **only one**:

1. The policy that gives the **largest discount** on this order wins (after the cap from step 2 and the mode from step 3).
2. On a **tie**, the one holding the card with the **closest expiry date** wins, so the customer does not lose balance.

Balance from different policies is **never added up** on the same order. For two balances to add up, the cards must be in the **same policy**, that is, the campaigns that create them must point to the same policy.

## Step 5 — The requested amount

When the integration says how much it wants to redeem (`amountToRedeem`), that amount limits the redemption. Each policy is evaluated with the whole requested amount, and only then the winner is chosen, so a policy that loses does not reduce the amount of the one that wins.

## Examples

In the examples, orders have no percentage cap unless stated, and the policies apply to the order's store.

| # | Customer balance | Result | Why |
|---|---|---|---|
| 1 | Policy A (aggregate): cards of $100 and $50. Policy B (aggregate): card of $120. | **$150**, from A | A adds up to $150 and B to $120. Policies compete: the larger wins. |
| 2 | Policy A (aggregate): $30 + $30. Policy B (single): $50. | **$60**, from A | A adds up to $60; B uses one $50 card. A wins. |
| 3 | Same as example 2, with `amountToRedeem` = $60. | **$60**, from A | Each policy is evaluated with the whole $60; A covers the $60. |
| 4 | Policy M (mixed): $50. Policy A (aggregate): $100. | **$100**, from A | Mixed does not add up with another policy; the largest discount wins. |
| 5 | Policy M1 (mixed): $40. Policy M2 (mixed): $70. | **$70**, from M2 | Even with both in mixed, different policies do not add up. |
| 6 | Policy A: $80, expires in December. Policy B: $80, expires in November. | **$80**, from B | Tied discount: the closest expiry date wins. |
| 7 | Policy A (aggregate): $10 + $20 + $30. | **$60** | Inside the same policy, aggregate adds up every card. |
| 8 | Policy B (single): $10, $20 and $30. | **$30** | Inside the same policy, single uses only the best card. |
| 9 | Order of $1,000. Policy A (aggregate, max 30%): $500. Policy B (aggregate, no cap): $200. | **$300**, from A | A's cap limits it to $300 (30% of $1,000), still larger than B's $200. |

## Frequently asked questions

**The customer has more balance than they could redeem. Why?**
The most common causes are balance split across different policies (only one is used per order, step 4), the policy cap (step 2) or the Single mode (step 3). If `redeemable.blocked` is filled, a wallet was blocked by the dynamic minimum (step 1).

**I want the cashback of two campaigns to add up on the same order.**
Put both campaigns on the **same** redemption policy, in Aggregate mode.

**I want the customer to use only the best credit, one per order.**
Use the **Single** mode on the policy.

## History

- **October 3, 2026** — different policies started competing with each other. Before, cards from different policies in Aggregate or Mixed mode were added up on the same order.

## See also

- [Reward by order](/docs/{lang}/api-reference/loyalty/checkout/reward-by-order)
- [Confirm order](/docs/{lang}/api-reference/loyalty/checkout/confirm-order-by-confirmtoken)
- [Update transaction](/docs/{lang}/api-reference/loyalty/checkout/update-transaction)
- [Loyalty cancellation](/docs/{lang}/guides/loyalty-cancellation)
