Wallet & Loyalty System

The wallet and loyalty system provides a rewards program with tiered benefits, wallet-based payment, and automated lifecycle management.

Core Concepts

Wallet

A digital wallet linked to a guest account. Stores reward points as monetary balance that can be applied toward bookings.

Loyalty Tiers

Guests are assigned to tiers based on their 12-month spending. Each tier has:

• Minimum spend threshold — amount needed to qualify
• Reward rule — conversion rate (spend → reward points) and expiry
• Redemption capability — percentage of booking that can be paid via wallet
• Benefits — redeemable perks (upgrades, early check-in, etc.)

Transaction Flow

Reward Credit (after booking checkout):
  UPCOMING → EARNED → USED/EXPIRED

Wallet Hold (during checkout):
  ON_HOLD → USED (confirmed) / RELEASED (cancelled)

Consumption:
  EARNED transactions consumed in FIFO order (earliest expiry first)
  WalletConsumedLog tracks which credit was consumed against which booking

Module Structure

wallet-loyalty/
├── service/
│   ├── WalletService          # CRUD, wallet details, applicability, reward calculation
│   ├── WalletOperationsService # hold/confirm/release/credit/expire/load/cancel
│   └── LoyaltyService         # CRUD, opt-in, tier progression, joining reward
└── scheduler/
    ├── LoyaltySchedulerService    # tier re-eval, renewal, checkout updates
    └── WalletAndLoyaltyScheduler  # @Scheduled cron triggers

Both website (customer-facing) and crs (agent-facing) depend on this module.

Database Tables

Table	Purpose
wallet	Guest wallet balance and status
wallet_transaction_log	All credit/debit/hold transactions
wallet_consumed_log	Tracks which earned transaction was consumed by which debit
wallet_reward_rule	Defines spend-to-reward conversion per tier
loyalty	Guest loyalty record (tier, spend, dates)
loyalty_tier	Tier definitions (level, thresholds, redemption %)
benefit	Available benefits (upgrades, perks)
loyalty_tier_benefit	M2M: which benefits belong to which tier
loyalty_joining_reward	Tracks joining bonus rewards