# Loyalty and Rewards API

All customer APIs are authenticated and derive the loyalty owner from the session.

## Customer

- `GET /api/v1/loyalty` — balance, debt, lifetime points, current tier, benefits, and next-tier progress.
- `GET /api/v1/loyalty/history?page=&limit=` — paginated immutable ledger.
- `GET /api/v1/loyalty/tiers`, `GET /api/v1/loyalty/rewards`.
- `POST /api/v1/loyalty/redeem` — requires `Idempotency-Key` and reward ID.
- `GET /api/v1/loyalty/vouchers` — owner-specific coupon entitlements.
- `GET /api/v1/loyalty/referral`, `POST /api/v1/loyalty/referral/claim`.

## Administration

- Loyalty accounts and referral listing.
- Tier, earn-rule, and reward listing/creation.
- `POST /admin/loyalty/adjustments` requires `loyalty.points.adjust`, a non-zero integer delta, reason, and idempotency key.

## Policy

Purchase points are awarded only after authoritative PAID processing. Eligible value is discounted merchandise (`subtotal - discountTotal`), excluding shipping, tax, and duties. Money is divided by configured `amountUnit`, floored to whole units, then multiplied by configured points.

Verified-review rewards require APPROVED and verified purchase. Referral rewards require the referred account's qualifying paid Order. Birthday events use `BIRTHDAY:user:year`; February 29 follows the actual calendar date.

Ledger entries are never edited. Refund reversals append negative entries. If already-spent points prevent a complete debit, available points floor at zero and the remainder becomes explicit `pointsDebt`; later earnings repay debt first.

Redemption locks the account/reward, validates limits, spends earliest-expiring allocations first, and creates at most one result per account/idempotency key. Coupon rewards reuse Phase 5 Coupon and issue an owner-specific entitlement.

Expiry is configured per earn rule and reconciled in bounded daily batches. No direct balance/tier mutation API exists.