pos_loyalty_reward_qty_limit/readme.md

POS Loyalty Reward Quantity Limit

Overview

This custom Odoo 19 module modifies the Point of Sale (POS) loyalty reward mechanism. It enforces a strict upper limit on the quantity of a reward product that can be applied to a single POS transaction.

By default, Odoo's loyalty engine allows customers with excess loyalty points to multiply a single reward rule, applying it multiple times to their cart in a single click. This module intervenes in this process by ensuring that the "Quantity Rewarded" (reward_product_qty) defined in the Loyalty Reward configuration acts as an absolute maximum per transaction.

Features

• Strict Limit Enforcement: Prevents the system from giving out more free items than specified in the reward_product_qty field.
• Accurate Point Deduction: Automatically scales the required loyalty points deducted from the customer's wallet to match the capped quantity, ensuring no points are overcharged.
• Dynamic UI Validation: Updates the Point of Sale UI to dynamically hide or disable the reward button once the maximum quantity has been reached in the cart.

Use Case Example

Scenario: A retail store runs a promotion where customers can redeem 100 points for 1 free coffee. Problem in standard Odoo: If a customer has 300 points, clicking the reward will automatically add 3 free coffees to the cart and deduct 300 points. Solution with this module: The module checks the "Quantity Rewarded" field (which is set to 1). When the customer clicks the reward, only 1 free coffee is added, and only 100 points are deducted. The reward button is then disabled for that transaction.

Installation

1. Move the pos_loyalty_reward_qty_limit folder into your Odoo custom/ addons directory.
2. Ensure you have the point_of_sale and pos_loyalty modules installed.
3. Turn on Developer Mode.
4. Go to Apps -> Update Apps List.
5. Search for POS Loyalty Reward Quantity Limit and install it.

Technical Details

This module patches the PosOrder.prototype located in the base point_of_sale frontend assets. Specifically, it overrides:

• _computeUnclaimedFreeProductQty
• _computePotentialFreeProductQty

It dynamically calculates the maxAllowed available quantity by subtracting the already claimed amount from the configured reward_product_qty.