Scout — Full Product Context → feature documentation

Rewards

A shared primitive — 'this scout has earned something they can redeem in the store' — plus its first consumer, the rebuilt referral ladder.

Summary

A shared primitive — "this scout has earned something they can redeem in the store" — plus its main consumer, the referral ladder. A UserReward ledger (backend/prisma/schema.prisma, migration backend/prisma/migrations/20260901180000_user_rewards/migration.sql) records every reward ever earned; RewardsService.grant() (backend/src/rewards/rewards.service.ts:84) reserves a ledger row, mints a single-use Shopify discount code scoped to that reward's kind, and raises a Notification (found on the next poll, and pushed to the phone under the Messages switch when push is enabled).

Nine kinds are defined today (backend/src/rewards/reward-kinds.ts), and since the 2026-10-19 repricing the referral ladder pays out exactly one of them: free_earned_patch at 10 qualified friends — "patch on us", $8 off any patch in all-patches (which the store only sells to a scout who has earned it), no minimum, so redeemed alone it is a $0 order with the store's standing free US shipping. It is paid once per referrer. No rung grants cloud-album access any more (see referral-and-invite.md). The other six kinds — pct_10_off, pct_20_off, patch_bogo (the 2026-09-22 rungs, dropped 2026-10-19), free_scout_patch, free_snapback, snapback_bogo — stay fully defined so any code already issued keeps rendering and expiring normally, and remain grantable by hand from Admin → Store → Rewards, but no ladder rung names any of them (see "What this feature does NOT do").

The eighth, patch_voucher, is not a referral reward at all. It is reserved for a monthly voucher granted by a subscription that is not live yet — one per billing month, granted by VoucherService, never by the ladder (the internal subscription doc has the detail). Its economics are free_earned_patch's exactly — both spread one shared constant, ONE_FREE_PATCH (reward-kinds.ts:128-137): $8 off any patch in all-patches, no minimum, no cap. Only the copy ("Patch voucher") and the expiry differ: 365 days rather than 90 (reward-kinds.ts:154-160). Its codes are prefixed SCOUT-VOUCHER-. Nothing can be bought that grants it, so nobody receives this kind today.

The ninth, zoo_snapback_giveaway, is also outside the ladder. It is the prize in the Saint Louis Zoo hat giveaway, granted by hand to each winner from Admin → Store → Rewards: $20 off (the hat's sale price) the saint-louis-zoo-snapback product, no minimum, no cap, single use, code prefix SCOUT-ZOOHAT-. It expires in 7 days, the window the giveaway's rules give a winner. It is flat rather than a percentage so a second hat in the cart is still paid for, and it does not survive a price rise: above $20 a winner would owe the difference, so raise it with the price.

A reward's discount is a RewardValue: either a flat dollar amount ({ kind: 'amount'; usd }, minted as Shopify's customerGets.value. discountAmount, unchanged from before) or, new as of the 2026-09-22 repricing, a percentage ({ kind: 'percent'; fraction } — 0.1 for 10%, 0.2 for 20% — minted as customerGets.value.percentage, rewards-shopify.service.ts's buildDiscountInput). Not every reward is redeemable on its own:

A minimum could not have bought what it appeared to buy in any case. Shopify counts only the discount's own scoped items toward a minimum purchase amount ("If the discount applies to a specific product or collection, then only these items contribute to the minimum purchase amount" — Shopify Help Center, Amount off discounts). So a product-scoped reward's minimum is either below the item's price, changing nothing, or above it, requiring the scout to buy two of the rewarded item. An earlier revision set the $30 Snapback's minimum to $38 intending "free hat if you also buy a patch"; the patch contributes nothing to that test, so it was buy-one-get-one. Widening the scope is not a fix either — scope also governs what the discount may be spent on, so letting patches satisfy the hat's minimum would let $30 come off a cart of patches. "Buy X, get Y free" needs discountCodeBxgy, a different primitive this feature does not use.

snapback_bogo is never earned — it is granted only as free_snapback's fallbackKind once that cap is exhausted, and it is one of the two kinds that carries a minimum. That is not an inconsistency but the same rule read forwards: because Shopify counts only the discount's own scoped items, a $60 minimum on a discount scoped to the $30 hat means exactly "two hats in the cart". $30 off $60 with appliesOnEachItem: false is one hat paid for and one free. It is the single shape a scoped minimum expresses correctly, and it is the same mechanic the old $38 minimum produced by accident on a reward that was supposed to be free.

patch_bogo — the 5-friend rung of the 2026-09-22 ladder, on no rung since 2026-10-19 — uses the identical shape one size down: $8 off a $16 (1,600-cent) minimum, scoped to the all-patches collection. Shopify again counts only the scoped items, so while single patches are $8, $16 of patches in the cart is "two patches, one of them free," not "buy a patch and get $8 off something else." Unlike snapback_bogo it was directly earnable (2026-09-22 to 2026-10-19), not merely a cap fallback.

Why the cap has a fallback rather than a waitlist

Hitting a cap used to set the row waitlisted — a status nothing promotes and nothing expires, so the scout kept a drawer badge for a reward they could never redeem, and (before the CAP_CONSUMING fix) each one permanently burned a slot. A fallbackKind replaces that dead end with something real: the row BECOMES the fallback kind and mints it, so the same milestone pays out a different reward because the free ones ran out. Rewriting the row rather than adding a second one keeps @@unique([userId, sourceRef]) meaningful — one rung, one reward, whichever it turned out to be.

The waitlist branch still exists for a capped kind with no sensible consolation (fallbackKind: null), and is tested by temporarily clearing the snapback's fallback, since no shipping kind reaches it. A test also asserts that every capped kind HAS a fallback, so adding a capped kind cannot reintroduce the dead end by omission. Only free_snapback (cap 30) is a capped kind today — the one currently-earnable kind (free_earned_patch) carries no cap (cap: null, reward-kinds.ts), so the fallback machinery exists but nothing on the shipped ladder exercises it.

The trigger is the referral ladder (backend/src/referral/referral-ladder.ts), repriced 2026-10-19 to one rung: 10 qualified friends → free_earned_patch. It replaced the 2026-09-22 store-promo ladder (1 → pct_10_off, 3 → pct_20_off, 5 → patch_bogo, 10 → permanent cloud album, no store reward), which had itself replaced the 2026-09-03 merchandise ladder. A free good at the top rung is safe where it was not at one friend: ten real-looking accounts that each collect a patch is far above the farming price referral-ladder.ts's header comment guards against. The ladder is editable at runtime from Admin → Referral Ladder (see referral-and-invite.md), so the threshold and reward kind can move without a build. Shipped 2026-09-01 (merchandise ladder), repriced 2026-09-22 (store promos) and 2026-10-19 (patch on us), no feature flag.

Status

Fully shipped, not flagged. No feature-flag check gates any code path under backend/src/rewards/ or its mobile/store surfaces. GET /api/rewards/unclaimed-count and the four admin routes are unconditionally live.

Minting works end to end in production as of 2026-09-02. It did not earlier that day — the Shopify app lacked write_discounts/read_discounts and every grant parked as pending — and the fix was two steps, both needed: release an app version carrying the scopes (scout-sync-6), and re-approve the install on mjhd81-vs, because releasing a version does not re-grant on an existing install. Verified afterwards by re-minting a parked row: pending → issued with a live gid://shopify/DiscountCodeNode/… and a 90-day expiry.

User-facing surfaces

How it works

  1. Trigger. The main caller of grant() is ReferralQualificationService (backend/src/referral/referral-qualification.service.ts), invoked from the same sync-time qualification pass referral-and-invite.md documents. It grants every ladder rung the referrer's qualified-friend count has reached, not only the highest one — see referral-and-invite.md for why. region:<slug> is reserved in sourceRef's shape for a future region-completion consumer that does not exist yet. The other callers are an admin's manual grant (backend/src/admin/api/admin-api.controller.ts:140) and, for patch_voucher only, VoucherService (a subscription that is not live yet; the internal subscription doc has the detail), whose sourceRef is subscription:<plan>:<yyyy-mm> — one per billing month, so the (userId, sourceRef) uniqueness below is what stops a month paying twice.

  2. Grant, in order (rewards.service.ts): refuse guests and missing profiles → generate the discount code → prisma.userReward.create() with status: 'pending' and that code already written to the row (the row is reserved before any network call; a P2002 on the (userId, sourceRef) unique constraint means this reward already exists and the call is a no-op) → a non-transactional cap check for capped kinds → mint a single-use Shopify code via RewardsShopifyService.mint() → mark issued with the node id, issuedAt, expiresAt → best-effort notify. A Shopify failure between reserve and mint leaves the row pending (visible in admin, re-mintable via remintPending()) rather than losing the reward or double-minting.

    A stuck row heals itself on the next grant for the same reward. The (userId, sourceRef) unique constraint means a later grant for the same rung raises P2002; instead of reporting duplicate blind, grant() reads the row (finishOrDuplicate) and, if it is still pending with no shopifyDiscountNodeId, delegates to remintPending(). That node-id check — not the status — is what keeps this apart from a double-mint, because the dangerous case is precisely a row that still reads pending after a crash. Anything else (issued, waitlisted, redeemed, expired, revoked, or pending-with-a-node-id) still returns duplicate cheaply. Retries are rate-limited per row by an in-process cooldown (HEAL_COOLDOWN_MS, 15 minutes) so a permanently-failing cause — such as the missing all-patches collection — cannot become a retry storm; a refused attempt returns mint_failed, which leaves Referral.rewardedAt honestly null.

    Reserving the code before the mint is what makes a crash recoverable. Without it, a process death between a successful mint and the "issued" write is indistinguishable from a mint that never ran, and an admin re-mint would put a second live single-use code against one reward — two codes, only the later one revocable, and markRedeemed unable to ever match the first. Persisting it early leaks nothing: toRewardDTO withholds discountCode for every status but issued.

  3. Minting (rewards-shopify.service.ts): resolves the reward's scope handle (a product or collection handle) to a Shopify GID via productByIdentifier/collectionByIdentifier (rewards-shopify.service.ts:143-167), then calls discountCodeBasicCreate with usageLimit: 1, appliesOncePerCustomer: true, customerSelection: { all: true } (forced, not chosen — Shopify has no way to bind a code to a Scout account), combinesWith: { productDiscounts: false, orderDiscounts: false, shippingDiscounts: true } (rewards-shopify.service.ts:buildDiscountInput) — one reward code per order, full stop; another reward code or an ad code cannot stack with it. Free shipping stays on because it is an automatic shipping discount, not a product/order one, and turning it off would quietly start charging delivery on a reward order. This used to combine with product discounts (productDiscounts: true) because the completed-set bundle price was itself an automatic product discount at the time; since 2026-09-02 a completed set's price is the set product's own Shopify price (see mobile-store.md), so nothing needs to combine with it any more and the flag was turned off.

  4. Cap enforcement (rewards.service.ts, CAP_CONSUMING): only free_snapback carries a cap (30 — reward-kinds.ts). The count query includes pending, issued and redeemed rows and deliberately excludes waitlisted — a waitlist entry is a place in a queue, not an allocated hat. (It used to be counted, which meant every waitlist entry burned a slot permanently: nothing promotes a waitlisted row and the sweep never touches one, so the effective cap ratcheted toward zero while stock sat unsold.) A grant that would push the count past the cap is marked waitlisted instead of minted, and still raises a notification — the calling code explains why: "the scout earned this the moment the milestone was crossed, so a waitlisted outcome still counts". pending is counted: it passed the cap check and is waiting only on a mint, so its slot is genuinely spoken for.

  5. Notify. UserNotificationsService.create() writes a reward_earned Notification row (rewards.service.ts:255-270); failure here is swallowed and logged, never fails the grant.

  6. Redemption. The existing orders/paid webhook handler (backend/src/shopify-webhooks/handlers/orders-paid.handler.ts:113-124) iterates the order's discount_codes[] and calls RewardsService.markRedeemed(code, orderId) (rewards.service.ts:406-420), which matches an issued row by code and marks it redeemed. This runs last and is wrapped in try/catch per code — a failure here must never fail the webhook (a throw would delete the WebhookDelivery row and make Shopify retry an already-processed order).

  7. Expiry sweep. A daily 4AM cron (rewards-expiry.service.ts, chosen to avoid the 3AM test-account cleanup) marks issued rows past expiresAt as expired. That is all it does. This is bookkeeping only — Shopify's own endsAt already stops the code working at checkout.

    It does not touch pending rows. It used to write them off after 7 days to free their capped slot, and that made an earned reward unrecoverable: remintPending refuses a non-pending row, grant() is blocked by the (userId, sourceRef) unique constraint, and the referral that earned it is already stamped qualifiedAt so it is never re-evaluated. Past day 7 the reward was gone through every code path in the repo. A pending row cannot run away with a cap (the cap is checked before the mint, so a kind can never hold more pending rows than its cap), it heals itself on the next grant for that same reward (see #2), and an admin revoke is the way to release one that never will — a decision a person makes rather than one a nightly job makes on their behalf.

    It also does not serve the waitlist. Nothing anywhere promotes a waitlisted row to issued.

  8. Revoke. Admin-only (rewards.service.ts:298-312): deactivates the Shopify discount first (a throw here is not caught, so a failed kill surfaces to the admin as an error rather than a silent success), then marks the row revoked. Order matters — marking the row first and having Shopify reject the deactivation would leave the ledger saying "revoked" while the code still works, with revokedAt now short-circuiting any retry.

  9. Apply to cart. /app/rewards writes the same non-httpOnly scout_discount cookie ad traffic has used for months (store/lib/store/rewards.ts:142, applyRewardToCart) — stashing an ad-link code it displaces so the cart can write it back later (see mobile-store.md, "The discount cookie follows the choice") — pins the reward for the session, then routes back to the store home. createCheckoutSession (pre-existing, store/lib/shopify/cart-actions.ts) already reads this cookie and passes it as discountCodes at checkout. There is no server-side cart on this stack.

    Buy now applies a voucher too (2026-11-06): ?buynow=1 has no cart, so BuyNowButton writes the chosen reward's code to the same cookie at the tap (patch-shop.md, "Buy now"). The hat giveaway message links there.

Data model

UserReward (user_rewards table, backend/prisma/migrations/20260901180000_user_rewards/migration.sql):

Field Notes
id UUID PK
userId not FK'd to profiles (matches the referral models' pattern)
kind free_earned_patch | free_scout_patch | free_snapback | snapback_bogo | pct_10_off | pct_20_off | patch_bogo | patch_voucher | zoo_snapback_giveaway
status pending | issued | waitlisted | redeemed | expired | revoked
sourceRef referral:milestone:<n>; admin:<adminId>:<timestamp> for manual grants; subscription:<plan>:<yyyy-mm> for a patch_voucher (no such row exists yet); region:<slug> reserved, unused
discountCode reserved on the pending row before the mint is attempted (null only on a waitlisted row, which never got one); the value the orders/paid handler matches on. 48 bits of entropy after a per-kind prefix
shopifyDiscountNodeId admin-only handle, used by revoke()/deactivate(); never returned to the app
minSubtotalCents copied from the kind config at grant time
issuedAt, expiresAt, redeemedAt, revokedAt, orderId lifecycle timestamps

@@unique([userId, sourceRef]) is the whole idempotency guard — a qualification pass that fires twice for the same milestone cannot mint twice. Indexes: (userId, status) for the unclaimed-badge count, (userId, createdAt DESC) for the list query, and (discountCode) — unique — for the webhook lookup.

(discountCode) was a plain index and became unique in backend/prisma/migrations/20260902100000_user_rewards_discount_code_unique/migration.sql (hand-written, like every migration here). markRedeemed resolves a redemption with findFirst({ discountCode, status: 'issued' }), which would silently pick one row if two ever shared a code — marking the wrong scout's reward redeemed against someone else's order. Postgres allows any number of NULLs under a unique index, so waitlisted rows are unaffected.

No schema change was needed for the notification: Notification.type is a plain String column (not an enum).

API surface

App-facing, JwtAuthGuard (backend/src/rewards/rewards.controller.ts):

Admin-only, AdminGuard (backend/src/admin/api/admin-api.controller.ts:75-159):

Key files

Configuration and flags

Runbook: the all-patches Shopify collection — DONE 2026-09-02

Created as gid://shopify/Collection/689898815648, handle all-patches, holding 2,246 products. free_earned_patch can now mint; all four reward scopes were verified to resolve to real GIDs against production. Reproducible via backend/src/scripts/create-all-patches-collection.ts (--apply), which is idempotent — it reports an existing collection and changes nothing.

Kept below because the reasoning is what stops someone "simplifying" the scope later.

Why a collection at all. Shopify's DiscountItemsInput — the scope on a basic code discount — accepts exactly three shapes:

all: true                              every product in the store
products:    { productsToAdd: [GID] }  an explicit list of product IDs
collections: { add: [GID] }            an explicit list of collection IDs

There is no tag field and no product-type field. (An earlier design of this feature scoped by productTypes; that key does not exist in the API and every grant would have thrown. See rewards-shopify.service.ts:100-125.) So "any patch" has to be expressed as a collection ID — not because a collection is wanted, but because it is the only container the discount API accepts. The alternative, enumerating every patch product GID into each discount, is worse on every axis: a large payload per mint, a Shopify-imposed list cap, and any patch added later silently falls outside every already-issued reward.

This is NOT a Scout collection. The word means two unrelated things here, and conflating them is the easy mistake:

Scout collection Shopify collection
Lives in Scout's collections table Shopify catalog
Example National Parks, Civil War Battlefields all-patches
Drives app shelves, sync, earn-a-set progress nothing in Scout
Users see it yes no

Nothing in store/lib/ reads Shopify collections — there are zero call sites. Scout's shelves are built entirely from Scout's own database. all-patches is therefore invisible plumbing: no app surface, no store shelf, no content publish, no sales-channel publication required. It exists only so a discount code has something to point at, and it must never be added to Scout's collections table.

Steps. In Shopify Admin → Products → Collections → Create collection:

  1. Title anything readable (e.g. "All patches — rewards scope"). What matters is the handle, which must be exactly all-patches to match ALL_PATCHES_COLLECTION (reward-kinds.ts). Shopify derives the handle from the title, so check and correct it in the SEO/URL field.
  2. Collection type: Automated (not Manual). Automated keeps itself current as patches are added; a manual collection would silently go stale and new patches would fall outside the reward.
  3. Condition: Product type is equal to Iron-on Patch. That is the type all 2,166 patch products already carry, so no tagging work is needed. A product-tag rule works equally well if a tag is preferred later — the requirement is only that some rule fills the collection automatically.
  4. Leave it unpublished from every sales channel. resolveScope looks it up through the Admin API by handle (collectionByIdentifier), which does not care about publication, and leaving it unpublished keeps it off the storefront.

Deliberately excluded: scout-patch. It is the only product typed Patch rather than Iron-on Patch, and it is what the 3-friend rung (free_scout_patch) hands out. A rule on Iron-on Patch therefore leaves it out, which is intended — it keeps rungs 1 and 3 genuinely different rewards and preserves the ladder's escalation in KIND, not just value (see the reward-kinds.ts header). Retyping scout-patch to Iron-on Patch would fold it in and let the 1-friend reward buy the branded emblem; do that only as a deliberate product decision, and update this section if so.

Verifying it worked. Grant a reward to a test account and confirm the row reaches issued with a discount_code. No backfill is needed for rewards that failed before the collection existed: they stay pending, and the next qualification for that referrer re-attempts the mint automatically (finishOrDuplicate), as does the admin re-mint button.

Edge cases and known limits

What this feature does NOT do

Tests that cover it

Backend (backend/src/rewards/):

Store / mobile:

Maestro (added 2026-09-02, run against a production-simulator build on prod):

Open questions