pos_loyalty_usage_limit_custom/README.md

POS Loyalty Usage Limit

Overview

This custom Odoo 19 module enhances the Point of Sale (POS) Loyalty and Promotions system by introducing redemption usage limits on individual loyalty cards. It allows administrators to restrict how many times a customer can use their loyalty card to redeem rewards within a specific time period (per day, per month, or per year).

Features

• Flexible Limits: Set usage limits to be enforced per day, per month, or per year.
• Card-Level Configuration: The limit configuration is set individually on each loyalty.card, allowing some VIP cards to be unlimited while standard cards are restricted.
• Smart POS UI Filtering: In the POS interface, if a card has reached its limit, the "Reward" button is automatically hidden, preventing cashiers from attempting invalid redemptions.
• Offline/Online Synchronization: The frontend logic seamlessly blends backend historical usage data with current un-synced POS session data to calculate real-time usage.
• Strict Backend Validation: A secure RPC validation check runs at checkout, preventing users from bypassing the limits by using the same card concurrently across multiple active POS sessions.

Configuration

1. Navigate to Sales > Products > Discount & Loyalty and open a loyalty program.
2. Click on the Cards smart button or directly navigate to a specific Loyalty Card.
3. Check the Limit boolean checkbox to enable the restriction.
4. Specify the Limit Count (e.g., 1).
5. Choose the Limit Period (Per Day, Per Month, or Per Year).
6. If the Limit checkbox is left unchecked, the loyalty card can be used indefinitely.

Technical Details

• Backend Validation: Overrides validate_coupon_programs in pos.order to ensure real-time limit adherence when processing payments.
• Frontend Filtering: Patches getClaimableRewards in PosOrder.prototype to hide unavailable rewards proactively.
• Usage Tracking: Computes period usage counts by scanning the loyalty.history records dynamically.