Adjust — a type='adjust' row in reward_points. Positive or negative. Used for manual operator corrections, refund clawbacks, and migrations. Never auto-fired except by the order listener's revoke path.
Available balance — the running SUM(points) across every transaction type for one user, floored at zero. The number that gates redemption.
Bonus — a type='bonus' row. Reserved for marketing campaigns (e.g., signup bonus, review bonus). Only BonusPoints writes this type.
Minor unit — the smallest unit of the store currency (a cent: 1/100 of a dollar). All money in the platform is stored as int64 minor units to avoid floating-point error. $49.90 = 4990.
Deferred bonus — in this module, the parallel concept is the revocation path: points earned at paid are clawed back if the order later moves to cancelled or refunded. The phrase "deferred bonus" itself belongs to the promotions module's post-order engine, which is unrelated.
Earn — a type='earn' row. Written by the OrderListener on transitions into paid or completed.
Effective amount — the order's subtotal − discount_total in minor units. The base on which points_per_unit is applied. Tax and shipping are excluded.
Expire — a type='expire' row, negative. Written by ExpireOldPoints for points older than expiry_days.
Expiry days — the per-tenant config knob (reward_config.expiry_days) that defines how long earned/bonus points stay live. 0 = no expiry.
reward_config — the single-row table holding per-tenant program settings. id = 1 always.
reward_points — the ledger table. One row per credit or debit. The single source of truth for balance.
reward_rules — the rule-CRUD table for bonus events. Editable via the admin Rules tab; auto-fire glue for non-order_complete events not yet wired.
reward_point_rates — roadmap table for per-object earn-rate overrides. Code exists, no migration ships it.
Idempotency — for earn: at most one earn row per order_id. For revoke: at most one negative adjust row per order_id. Both checked before INSERT.
max_redeem_percentage — the cap on what fraction of an order total can be paid with points. Validated server-side; the storefront UI mirrors it.
min_redeem_points — the floor on the customer's available balance before redemption is allowed.
Module gate — the reward-points-enabled check fired at three layers (router middleware, service guard, listener guard) before any side-effect.
Order listener — the OrderListener struct that subscribes to order.statusChanged and dispatches earn or revoke. Registered once at startup.
points_per_unit — points credited per $1.00 of effective amount. Default 1.
Redeem — a type='redeem' row, negative. Written when the customer applies points at checkout.
Redemption rate — redemption_rate in reward_config. Minor units (cents) each point is worth at checkout. Default 1.
Revocation — the OrderListener's clawback path. Triggers on transitions into cancelled or refunded. Writes a negative adjust row tagged with the order_id.
Tier / loyalty tier — Bronze/Silver/Gold-style band. Not implemented in this module.
Tenant — one storefront with one isolated DB schema. Reward config and ledger live entirely per-tenant. There is no platform-wide reward pool.
