Promotions and loyalty

01Anatomy of a promotion rule

Every promotion has three parts: conditions, an action and limits. Conditions decide whether it applies: minimum cart total, specific products or categories, customer segment or loyalty level, first order only, channel (web or app), date range, day of week. The action is what it gives: percentage off, fixed amount off, a fixed price, buy X get Y, a free gift item, or free delivery. Limits keep it under control: total uses, uses per customer, maximum discount, budget. Promotions can be automatic (applied when conditions match) or manual (activated by a code or a button). Storing rules as data — rows with typed conditions and actions — instead of code is what lets marketing work without developers.

• Percentage: 10% off the cart or selected lines, optionally capped.
• Fixed: 5.00 off orders above 30.00.
• First order, birthday, loyalty level: conditions on the customer, not the cart.
• Gift item or free delivery: actions that change lines or fees, not just the total.

02Stacking, priority and exclusivity

Stacking means combining several promotions on one order. Without rules, discounts compound into losses. A practical model: each promotion has a priority and a stacking mode — exclusive (cannot combine with anything), combinable with any, or combinable only within its group. Decide the order of application too: percentage discounts usually apply before fixed ones, and line discounts before cart discounts, because the order changes the result. Decide whether a discount applies to the price before or after other discounts, and never let the total drop below zero or below a configured margin. Write these rules down as a short table that marketing approves; then implement exactly that table and test it.

03Best price for the customer

When several offers are eligible but cannot all stack, which one wins? The friendliest answer is: whichever combination gives the customer the lowest total. The engine first filters eligible promotions, then builds the valid combinations allowed by the stacking rules, simulates each on a copy of the cart, and picks the cheapest result — with a deterministic tie-breaker such as higher priority, then older promotion. The number of combinations grows fast, so keep it bounded: exclusive offers form one-item scenarios, and combinable ones usually stack greedily within their group. Return not only the total but an explanation per line ("Summer sale −10%"), which shows on the receipt and makes support questions easy.

1type Cart = { lines: { id: string; price: number; qty: number }[] };
2type Promo = { id: string; priority: number; exclusive: boolean; apply: (c: Cart) => number };
3 
4// Returns the discount combination with the lowest final total
5export function bestScenario(cart: Cart, eligible: Promo[]) {
6  const subtotal = cart.lines.reduce((s, l) => s + l.price * l.qty, 0);
7  const stackable = eligible.filter((p) => !p.exclusive).sort((a, b) => b.priority - a.priority);
8  const scenarios: Promo[][] = [stackable, ...eligible.filter((p) => p.exclusive).map((p) => [p])];
9 
10  let best = { promos: [] as Promo[], total: subtotal };
11  for (const promos of scenarios) {
12    const discount = promos.reduce((sum, p) => sum + p.apply(cart), 0);
13    const total = Math.max(0, subtotal - discount);
14    if (total < best.total) best = { promos, total };
15  }
16  return best; // ties keep the earlier, higher-priority scenario
17}

04Wallets, cashback and loyalty tiers

Cashback returns a percentage of an order to a customer wallet as store credit. Treat the wallet as a ledger: never store only a balance — store every credit and debit with a reason and a reference to the order, and derive or verify the balance from those rows. Credit cashback only after the order is delivered or the return window passes, otherwise people buy, collect and refund. Spending from the wallet is a payment method at checkout, applied after promotions. Loyalty tiers (for example Bronze, Silver, Gold) reward customers by spend or points over a period. Define how a customer moves up, when they can drop down, and whether there is a grace period. Points and balances often expire after inactivity; send a reminder before they do.

• Ledger rows: credit, debit, expire, manual adjustment — each with who and why.
• Manual adjustments by staff deserve an audit log, and large ones a second approval.
• Recalculate tiers on a schedule and sync them into customer segments.

05Referrals, vouchers and fraud checks

A referral programme rewards a customer for inviting friends: each user gets a code or link, the friend signs up through it, and both get a reward after the friend's first qualifying order. Track clicks and sign-ups, and for mobile apps use deferred deep links so the code survives the app install. Settle rewards in a delayed batch job, not instantly, so you can cancel rewards for refunded orders. Referrals and vouchers attract abuse: self-referrals with a second account, many accounts on one phone or card, shared codes on coupon sites. Basic checks catch most of it: same device, phone, card fingerprint or address as the referrer, order refunded, too many sign-ups from one code in a short time. Vouchers should be random, long enough to resist guessing, rate-limited and single-use when they carry value.

06Engine architecture: a pure pricing pipeline

The most reliable promotion engines are pure functions: given a cart, a customer context, a time and a list of active promotions, they return a priced cart and an explanation, with no database writes. That makes them easy to test with exact amounts, safe to run on every cart change, and identical on the cart page, checkout and admin previews. Structure the pipeline in stages: load candidate promotions (pre-filtered by date, channel and status with an index), evaluate conditions, build scenarios, apply actions on a copy of the cart, pick the best, and produce line-level adjustments. Side effects — counting a use, debiting a voucher, crediting cashback — happen later, only when the order is created or completed, inside the order transaction.

1type Ctx = { now: Date; customerId?: string; segment: string[]; channel: "web" | "app" };
2type Adjustment = { lineId?: string; promoId: string; amount: number; label: string };
3 
4// Pure: same input → same output, no I/O
5export function priceCart(cart: Cart, ctx: Ctx, promos: Promo[]) {
6  const eligible = promos.filter((p) => p.isActive(ctx.now) && p.matches(cart, ctx));
7  const best = bestScenario(cart, eligible);
8  const adjustments: Adjustment[] = best.promos.flatMap((p) => p.adjustments(cart));
9  return { total: best.total, adjustments };
10}

07Usage limits under concurrency

"First 500 customers" and "one use per customer" sound simple until 2,000 people check out in the same minute. Counting uses with a SELECT COUNT and then inserting is a race: everyone sees 499. Enforce limits with the database. For a global cap, keep a counter row and increment it conditionally (UPDATE promotions SET used = used + 1 WHERE id = :id AND used < max_uses) in the order transaction. For per-customer limits, insert a redemption row with a unique constraint on (promotion_id, customer_id). Release the use if the order is cancelled before payment. Budget caps work the same way with amounts instead of counts. Validate again at checkout, and accept that the cart page may show a promotion that is gone a second later; tell the customer clearly.

08Measuring whether a promotion works

A promotion is a cost; the question is what it bought. Track per promotion: orders, discount given, revenue, margin after discount, new versus returning customers, and redemption rate. Raw numbers mislead, because many customers would have bought anyway. The honest measure is incrementality: compare a randomly chosen group that receives the offer with a holdout group that does not, and look at the difference in orders and margin. Even a simple 90/10 split on a newsletter coupon gives better answers than any dashboard. For loyalty programmes, watch repeat purchase rate and time between orders by tier, plus the liability of outstanding points or wallet balances, which finance may need to treat as a deferred cost.

• Store the applied promotion IDs and amounts on order lines for reporting.
• Report discount cost as a percentage of revenue per campaign.
• Keep a holdout group for automated offers such as win-back coupons.

09Points and wallet accounting edge cases

Ledger-based wallets raise edge cases worth deciding in advance. Expiry: with first-in-first-out spending, debits consume the oldest credits first, so an expiry job knows exactly which amounts remain from each credit; store remaining amounts per credit lot to make that cheap. Partial refunds: if an order paid partly with wallet credit is partly refunded, decide whether credit or card is returned first, and reverse cashback proportionally. Concurrency: debits must lock the customer's wallet row or use a conditional update so two parallel checkouts cannot spend the same balance. Currency: a wallet should hold one currency. Legally, in some countries store credit or points can count as stored value or e-money, with consumer and accounting rules, so check before letting customers top up with real money.