# Loyalty Service — Enterprise Loyalty Platform

> Phase 7.6 Wallet complete (7.0–7.5 engines + immutable wallet ledger). Independent shared service — **not** part of CRM.

Reusable by Restaurant, Marketplace, Ecommerce, Academy, Booking, Healthcare,
Salon, Gym, and future modules via API + Events only.

## Ownership

| Owns | Does not own |
| --- | --- |
| LoyaltyProgram, MembershipTier, Member + lifecycle | CRM sales entities |
| MembershipLifecycleEvent history | Accounting / Posting Engine |
| PointAccount + immutable `PointLedgerEntry` | Notification delivery |
| Reward catalog + `RewardRedemption` lifecycle | Analytics store (later) |
| Campaign engine + applications | Identity / Gift card UI (7.7+) |
| Referral programs / codes / attributions | Payment gateway settlement |
| WalletAccount + immutable `WalletLedgerEntry` | |
| Loyalty audit trail | |

## Boundaries

- Independent database: `loyalty_db` (ADR-001, ADR-011)
- Row-level tenancy via `tenant_id` from request context (ADR-003)
- Point and wallet balances come **only** from immutable ledgers — never mutate a balance column
- Soft delete releases unique keys so codes can be reused; audit via `/api/v1/audit`
- Inter-service communication: REST + Events only (transactional outbox)
- Platform providers are **contracts only** under `app/providers/`
- Route permissions enforced (`loyalty.*`); invalid `X-Tenant-ID` rejected

## API Prefix

`/api/v1` on port **8004**

| Resource | Path |
| --- | --- |
| Programs | `/api/v1/programs` |
| Tiers | `/api/v1/tiers` |
| Members | `/api/v1/members` |
| Point accounts | `/api/v1/point-accounts` (+ ledger ops) |
| Rewards / Redemptions | `/api/v1/rewards`, `/api/v1/redemptions` |
| Campaigns | `/api/v1/campaigns` |
| Referrals | `/api/v1/referral-programs`, `/referral-codes`, `/referrals` |
| Wallets | `/api/v1/wallets` (+ `/balance`, `/ledger`, `/credit`, `/debit`, `/adjust`, `/transfer`) |
| Health | `/health` |

## Permissions

`loyalty.*` including points, rewards, campaigns, referrals, wallets, audit trees.

## Run locally

```bash
cd backend/services/loyalty
pip install -r requirements.txt
pytest -q
uvicorn app.main:app --port 8004 --reload
```

## Related Documents

- [Phase 7.6](../../../docs/loyalty-phase-7-6.md)
- [Handover 7.6](../../../docs/phase-handover/phase-7-6.md)
- [Service Snapshot](../../../docs/service-snapshots/loyalty.yaml)
- [Module Registry](../../../docs/module-registry.md#loyalty)
- [ADR-011](../../../docs/architecture/adr/ADR-011.md)