Sathira Sri Sathara
abb760cc19
CI / test (push) Successful in 10m23s
- Added models for loyalty points allocation, redemption, rewards, tiers, tier history, and referrals. - Created business credit ledger entries, settlements, and settlement items models. - Developed services for loyalty operations including account management, point allocation, redemption, and referral handling. - Implemented wholesale credit management services for transactions and settlements. - Established routes for loyalty and wholesale admin and customer operations with appropriate middleware for authentication and permission checks. - Introduced validation schemas for loyalty and wholesale operations. - Set up cron jobs for loyalty reconciliation tasks such as birthday rewards and point expirations. - Created migration scripts to set up the database schema for loyalty and wholesale features. - Added unit tests for validation and policy enforcement in loyalty and wholesale services.
31 lines
1.9 KiB
Markdown
31 lines
1.9 KiB
Markdown
# 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.
|