Sathira Sri Sathara
abb760cc19
- 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.
1.9 KiB
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— requiresIdempotency-Keyand 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/adjustmentsrequiresloyalty.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.