# Phase Handover — Loyalty 7.3 Rewards Engine

## Metadata

| Field | Value |
| --- | --- |
| Phase ID | loyalty-7.3 |
| Title | Rewards Engine |
| Status | Complete |
| Service(s) | loyalty (`loyalty-service`, port 8004) |
| Version | 0.7.3.0 |
| Date | 2026-07-26 |
| ADR(s) | ADR-001, ADR-003, ADR-006, ADR-011 |

## Reusable Components

| Component | Location | Reuse notes |
| --- | --- | --- |
| RewardRedemption | `app/models/rewards.py` | Lifecycle + ledger linkage pattern |
| RewardsEngineService | `app/services/rewards_engine.py` | Compose with PointEngine via `auto_commit=False` |
| PointEngine auto_commit | `app/services/point_engine.py` | Required for multi-aggregate transactions |

## Public APIs

| Method | Path | Auth / Permission | Notes |
| --- | --- | --- | --- |
| POST | `/api/v1/rewards/{id}/redeem` | `loyalty.rewards.redeem` | Debits points; pending |
| GET | `/api/v1/rewards/{id}/redemptions` | `loyalty.redemptions.view` | Per-reward list |
| GET | `/api/v1/redemptions` | `loyalty.redemptions.view` | Filtered list |
| GET | `/api/v1/redemptions/{id}` | `loyalty.redemptions.view` | Detail |
| POST | `/api/v1/redemptions/{id}/fulfill` | `loyalty.rewards.fulfill` | pending→fulfilled |
| POST | `/api/v1/redemptions/{id}/cancel` | `loyalty.rewards.cancel` | Refunds points |

## Events

| Event type | Domain / Integration | Payload summary | Version |
| --- | --- | --- | --- |
| `loyalty.reward.redeemed` | Domain | redemption + reward + points | 1 |
| `loyalty.reward.fulfilled` | Domain | redemption id | 1 |
| `loyalty.reward.redemption_cancelled` | Domain | redemption + refund | 1 |

## Extension Points

| Extension point | How to extend | Forbidden uses |
| --- | --- | --- |
| Eligibility | Extend validators | Bypass PointEngine for paid rewards |
| Campaign grants | Call RewardsEngine from 7.4 | Direct balance mutation |
| Inventory | stock_limit / max_per_member | Negative redeemed_count |

## Known Limitations

- No scheduled redemption expiry
- No external partner fulfillment callbacks (7.9)

## Migration Notes

| Item | Detail |
| --- | --- |
| Alembic revision(s) | `0004_phase_73_rewards` |
| Upgrade steps | `alembic upgrade head` |
| Downgrade support | Yes |
| Breaking changes | None (additive) |

## Dependencies

| Dependency | Type | Required for |
| --- | --- | --- |
| loyalty-7.2 | Phase | PointEngine ledger |
| shared-lib | Library | Events, security, exceptions |

## Next Phase Entry

1. This handover + [loyalty-phase-7-3.md](../loyalty-phase-7-3.md)
2. Build Campaign Engine; grant points/rewards only via PointEngine / RewardsEngine
3. Suggested next: `loyalty-7.4` Campaign Engine

| Field | Value |
| --- | --- |
| Recommended next phase | loyalty-7.4 |
| Blockers for next phase | None |
| Entry checklist | Keep ledger immutable; reuse RewardsEngine + PointEngine |

## Completion Sign-Off

- [x] Quality gates passed
- [x] Tests green (72)
- [x] Documentation updated
- [x] Progress / next-steps / registries updated
- [x] Service Snapshot regenerated

## Related Documents

- [loyalty-phase-7-3.md](../loyalty-phase-7-3.md)
- [loyalty-phase-7-2.md](../loyalty-phase-7-2.md)
- [ADR-011](../architecture/adr/ADR-011.md)