Sign in
.md

Redemption policies

When an order asks for a redemption (for example, through 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): 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