Bean & Bloom Rewards: Earn, Expire, Refund, Tier and Transfer

Bean & Bloom Rewards: Earn, Expire, Refund, Tier and Transfer

You've joined the Loyalty Platform team at Bean & Bloom, a coffee chain with a points program. Members earn points on purchases, spend them on rewards, and lose them if they sit on them too long. The backend works for simple cases, but Support has escalated three wrong-balance tickets, and product has three features queued behind them (refunds, automatic tiers, household transfers). Points are always integers; money is integer cents; one day is 86 400 seconds.

Codebase

How your code is run

run(operations: list[list]) -> list executes the operations in order against a fresh program and returns one result per operation. Every operation is [name, ts, ...args]; ts is an integer number of seconds and never decreases from one operation to the next. Errors are returned as "error: <code>" strings, never raised.

Checks run in the order listed for each operation, and the first failure is the result. Two general rules: an unknown operation name returns "error: unknown operation" (before anything else); a wrong number of arguments or a ts that is not an integer returns "error: invalid arguments". Inside an operation, an id (member, purchase, promo, batch, redemption, household), a reward code or a tier name that is not a non-empty string, or a number argument that is not an integer, is also invalid arguments and is checked first. true/false are never integers. Two exceptions have their own codes, listed with the operations: a bad amount (invalid amount) and bad points (invalid points).

Part 1 operations

• tier is one of "base", "silver", "gold". amount is cents and must be an integer > 0.
• add_promo: percent must be in 101..1000 and start_ts < end_ts, else invalid promo. A promotion applies to a purchase whose time t satisfies start_ts <= t < end_ts. Several promotions in force at once do not stack: the highest percent wins. A promotion only exists from the moment it is added.
• Reward costs are in loyalty/config.py (coffee 150, pastry 220, sandwich 400, mug 900). Redemption ids count up with each successful redemption.

How earning works (the code in earn.py and config.py is canonical):

1. The earn rate comes from the member's tier: base 10, silver 15, gold 20, in thousandths of a point per cent (so base earns 1 point per dollar).
2. exact = amount * rate. Base points = exact / 1000 rounded to the nearest integer, halves rounded up (4.5 becomes 5; 4.4 becomes 4). All rounding in the program lives in loyalty/rounding.py.
3. If a promotion with percent P is in force at the purchase's time, bonus points = exact * (P - 100) / 100 / 1000 (computed from the exact, unrounded earn), rounded half up on its own. Base and bonus are rounded separately and then added; the purchase returns base + bonus.
4. Base points go into a bucket that expires 180 days after the purchase; bonus points go into their own bucket that expires 30 days after it. A bucket of 0 points is not created (but the purchase still exists).

How points are held and spent:

• A bucket is usable while now < expires_at. At exactly expires_at it is already gone (that is true for balance, for redeem, and everywhere else).
• balance is the sum of the unspent points in usable buckets. redeem needs at least the reward's cost.
• A redemption spends from usable buckets in this order: soonest expires_at first, then earliest earned time, then the bucket that was created first. A bucket may be spent partly.

Worked example

[["enroll", 0, "ana", "h1", "base"],
 ["add_promo", 1, "launch", 0, 2592000, 300],
 ["purchase", 100, "ana", "p1", 10000],
 ["purchase", 200, "ana", "p2", 10000],
 ["redeem", 300, "ana", "coffee"],
 ["balance", 2592099, "ana"],
 ["balance", 2592100, "ana"]]

returns [true, true, 300, 300, "rd-1", 450, 400]. Each purchase earns 100 base points plus a 200-point bonus (30 days). The coffee (150) is paid from p1's bonus bucket because it expires first (day 30 + 100 s), leaving it

1. At second 2592099 everything is still there (450); at 2592100 p1's bonus bucket has just expired (400).

Part 1: three wrong-balance tickets (LOY-3127, LOY-3140, LOY-3152)

Goal: make earning, expiry and redemption follow the rules above. Support's reports:

1. "I spent $4.50 and got 4 points. Our terms say halves round up. The promo bonus looks off in the same way."
2. "I redeemed a free coffee, then watched a pile of bonus points expire a week later. The app spent my long-lived points first."
3. "My promo bonus was still in my balance at the exact second it was supposed to expire."

tests/test_service.py has two failing tests that cover some of this; do not assume they cover everything. Where a rule is implemented is part of the job: fix the cause, not each symptom.

Part 2: refunds and cancelling a redemption (LOY-3188)

Goal: add refund and cancel_redemption. Both live in loyalty/refunds.py.

Refund rules. A refund reverses the points earned on that purchase (its base bucket and its bonus bucket, if any). Points are never recomputed; the purchase's actual buckets are what is reversed. For each of the two buckets, with consumed = points originally credited - points still unspent in it:

1. Whatever is still unspent in the purchase's buckets is removed. If a bucket has already expired, its unspent points are simply forgiven (nothing is taken for them).
2. The consumed points (spent on rewards) must still be given back: the total of consumed over the purchase's buckets is taken from the member's other usable buckets, soonest expires_at first (same order as a redemption), as far as they go.
3. Whatever cannot be covered becomes debt, a number on the member that never expires. balance is usable points - debt, so it can be negative. Any points a member gets later (a purchase, a restore, a transfer) raise the balance and so work the debt off; nothing else is needed to settle it.
4. A redemption needs balance >= cost (debt included), so a member in debt can be refused even though their usable buckets would cover the reward. Spending only ever takes points from usable buckets.

Cancel rules. A redemption can be cancelled while ts < redeemed_ts + 86400; at exactly that second the window is closed. Cancelling puts back the exact amounts into the exact buckets the redemption spent from, so each bucket keeps its original expires_at. If one of those buckets has expired by the time of the cancel, the points are put back but are no longer usable. redemption touched by refund means a bucket the redemption spent from was reversed by a refund (the points can no longer be restored). Cancelling does not use up a redemption id and the redemption keeps its id.

Worked examples

[["enroll", 0, "ana", "h1", "base"],
 ["purchase", 100, "ana", "p1", 10000],
 ["purchase", 200, "ana", "p2", 4000],
 ["purchase", 300, "ana", "p3", 2000],
 ["redeem", 400, "ana", "coffee"],
 ["refund", 500, "p1"],
 ["purchase", 600, "ana", "p4", 3000]]

returns [true, 100, 40, 20, "rd-1", -90, 30]. The coffee (150) is paid from p1 (100), p2 (40) and p3 (10). Refunding p1 must claw back 100 points, all already spent, so the member's other usable buckets are used (p3's remaining 10) and the remaining 90 is debt: the refund returns a balance of 0 - 90 = -90. The next purchase earns 30, which brings the balance to -60.

[["enroll", 0, "ana", "h1", "base"],
 ["purchase", 100, "ana", "p1", 10000],
 ["purchase", 200, "ana", "p2", 10000],
 ["redeem", 300, "ana", "coffee"],
 ["cancel_redemption", 400, "rd-1"],
 ["balance", 15552100, "ana"],
 ["cancel_redemption", 401, "rd-1"]]

returns [true, 100, 100, "rd-1", 200, 100, "error: already cancelled"]. p1's bucket expires at 100 + 180 days = 15552100: the cancel restored its points *into p1's bucket*, so they expire on schedule and the balance at 15552100 is 100 (p2's), not 200.

Part 3: tiers are earned, not assigned (LOY-3201)

Goal: a member's tier now follows their spending. This replaces the "tier is whatever it was at enrolment" behaviour of Parts 1 and 2.

Rules

1. Qualifying spend at time t is the total amount (cents) of the member's purchases made at times p with t - 365 days < p <= t, excluding refunded purchases. A purchase stops counting at p + 365 days exactly. A refund removes the purchase from the spend immediately (at the refund's ts), whatever tier the purchase earned at; refunding a purchase that has already left the 365-day window changes nothing.
2. The tier from spend is gold at spend >= 150000, silver at >= 50000, otherwise base (tiers.tier_for_spend).
3. The tier given to enroll becomes the member's minimum tier: a member's current tier is the higher of that and the tier from spend.
4. A purchase earns at the member's tier as of just before that purchase: the purchase's own amount does not count toward its own tier, but earlier purchases at the same ts do.
5. Tier changes affect only future purchases: points already earned (and refunds of them) are never recomputed.
6. tier returns [current tier, qualifying spend] as of ts.

Worked example

[["enroll", 0, "ana", "h1", "base"],
 ["purchase", 1, "ana", "p1", 49000],
 ["purchase", 2, "ana", "p2", 1000],
 ["tier", 3, "ana"],
 ["purchase", 4, "ana", "p3", 1000],
 ["refund", 5, "p1"],
 ["tier", 6, "ana"],
 ["purchase", 7, "ana", "p4", 1000]]

returns [true, 490, 10, ["silver", 50000], 15, 25, ["base", 2000], 10]. p2 (the purchase that reached $500) still earned at the base rate; p3 earned at silver. Refunding p1 pulls the member back to base: p1's 490 points are removed (balance 25), and p4 earns at the base rate again.

Part 4: household transfers and a year of history (LOY-3230)

Goal: add household point transfers, then make the balance and expiry queries fast enough for a program-wide nightly job over a year of daily purchases.

transfer_points. points must be an integer > 0 (else invalid points); member not found checks the sender first. Both members must have the same household_id. The sender needs balance >= points (debt counts, as for a redemption). The points are spent from the sender's usable buckets in the usual order, and for every bucket that gives points the receiver gets a new bucket with the same amount, the same earned_ts and the same expires_at (transfers preserve expiry; they never reset it). Transferred buckets are not tied to any purchase, so a later refund never reverses them. A refund of a purchase whose points were transferred out sees those points as consumed. Transfers do not affect tier spend.

expiring_soon. days must be an integer >= 1 (else invalid arguments). points is the unspent points in the member's usable buckets whose expires_at <= ts + days * 86400 (a bucket expiring exactly at the horizon counts); earliest_expiry is the smallest such expires_at, or null when points is 0. Debt is ignored here. expiry_digest (both arguments integers >= 1, else invalid arguments) counts the members whose expiring_soon points for that days are >= min_points, and totals those points. total_liability is the sum over all members of their usable points (debt is not netted).

bulk_purchases replays a quiet stretch of regular purchases for a cohort without a giant operation list. member_ids is a non-empty list of ids (shape problems are invalid arguments; duplicates are invalid batch); first_ts, every, count, spread must be integers and spread >= 1 (else invalid arguments); base_amount must be an integer > 0 (else invalid amount); every < 1 or count < 1 is invalid batch. For occurrence i = 0 .. count-1, at time first_ts + i * every, the member at list position j makes a purchase of base_amount + (i * 37 + j * 101) % spread cents with purchase id "<batch_id>:<member_id>:<i>". Each one behaves exactly like a purchase at that time (tier, promotions, buckets, spend), processed in time order and in list order within a time. The operation returns the total points earned. It is rejected with invalid batch unless every occurrence time lies between the largest integer ts of any earlier operation in the list (0 if none; an earlier operation counts even if it failed, was unknown or had the wrong number of arguments, as long as its ts is an integer) and this operation's own ts, both inclusive; and purchase exists if any generated purchase id is already used. A rejected batch changes nothing.

Worked example

[["enroll", 0, "ana", "h1", "base"],
 ["enroll", 0, "bo", "h1", "base"],
 ["enroll", 0, "cy", "h2", "base"],
 ["purchase", 100, "ana", "p1", 10000],
 ["purchase", 200, "ana", "p2", 20000],
 ["transfer_points", 300, "ana", "bo", 150],
 ["transfer_points", 301, "ana", "cy", 10],
 ["expiring_soon", 15552000, "bo", 1],
 ["expiring_soon", 15552100, "bo", 1]]

returns [true, true, true, 100, 200, 150, "error: different household", [150, 15552100], [50, 15552200]]. Ana's 100 points from p1 and 50 of p2's moved to Bo in two buckets that keep expiry dates 15552100 and

1. At 15552100 the first bucket is gone.

Scale. Hidden tests run tens of thousands of purchases through bulk_purchases and hundreds of expiry_digest, expiring_soon and total_liability calls in one run; the whole suite has a few seconds. Looking at all of a member's history on each query is too slow.

Notes

• earn.py, promos.py, members.py, validation.py and config.py are known-good.
• You may use the AI assistant freely; you are expected to verify what it produces.
• Later parts must not break earlier ones; hidden tests re-check earlier behaviour. Where a later Part changes a rule, the later rule wins and says so.
• Parts 1-3 is a strong result. Part 4 is a stretch.