Phase 7.3 — Rewards Engine
| Field |
Value |
| Identifier |
loyalty-7.3 |
| Status |
Complete |
| Module |
loyalty |
| Service |
loyalty-service |
| Version |
0.7.3.0 |
| Database |
loyalty_db |
| Depends On |
Phase 7.2 |
| ADR(s) |
ADR-001, ADR-003, ADR-006, ADR-011 |
| Manifest |
phase-manifest.yaml |
Objective
Deliver the Rewards Engine: redemption lifecycle on catalog rewards with points debited exclusively through the immutable Point Engine — without campaign rules, referral, wallet, or gift cards.
Scope
In Scope
- Reward inventory fields:
stock_limit, redeemed_count, max_per_member
RewardRedemption lifecycle: pending → fulfilled | cancelled- Redeem / fulfill / cancel APIs; list by reward and globally
- Points debit/refund via
PointEngineService (auto_commit=False composition)
- Permissions, events, validators, migration
0004_phase_73_rewards
- Tests + documentation + handover + service snapshot
Out of Scope
- Campaign rule engine (7.4)
- Referral / wallet / gift cards / analytics / partner APIs (7.5–7.9)
Redemption Rules
| Rule |
Detail |
| Active reward only |
Status must be active |
| Stock |
redeemed_count < stock_limit when limit set |
| Per-member cap |
Non-cancelled count ≤ max_per_member when set |
| Member |
Must be active |
| Points |
Debit via ledger; free (points_cost=0) skips ledger |
| Cancel |
Only from pending; refunds points; decrements stock counter |
| Fulfill |
Only from pending |
APIs
| Method |
Path |
Permission |
| POST |
/api/v1/rewards/{id}/redeem |
loyalty.rewards.redeem |
| GET |
/api/v1/rewards/{id}/redemptions |
loyalty.redemptions.view |
| GET |
/api/v1/redemptions |
loyalty.redemptions.view |
| GET |
/api/v1/redemptions/{id} |
loyalty.redemptions.view |
| POST |
/api/v1/redemptions/{id}/fulfill |
loyalty.rewards.fulfill |
| POST |
/api/v1/redemptions/{id}/cancel |
loyalty.rewards.cancel |
Events
| Event |
When |
loyalty.reward.redeemed |
Redeem (points deducted) |
loyalty.reward.fulfilled |
Fulfill |
loyalty.reward.redemption_cancelled |
Cancel + refund |
Migration
| Item |
Detail |
| Alembic |
0004_phase_73_rewards (down_revision 0003_phase_72_points) |
| Breaking |
None — additive columns + table |
Tests
Command: cd backend/services/loyalty && pytest -q → 72 passed
Known Limitations
- No automatic redemption expiry worker
- No partner fulfillment webhooks (7.9)
- Campaign-driven rewards deferred to 7.4
Next Phase
Phase 7.4 — Campaign Engine
Related Documents
