103 lines
3.9 KiB
Markdown
103 lines
3.9 KiB
Markdown
# POS Loyalty Auto Level Update
|
|
|
|
Automatically updates a customer's loyalty membership level after every POS transaction (sale or refund).
|
|
|
|
## Overview
|
|
|
|
This module extends Odoo 19's Point of Sale to support **automatic multi-level loyalty membership management**. When a customer completes a purchase or receives a refund at the POS, the module recalculates their total spending and assigns the appropriate loyalty tier — no manual intervention required.
|
|
|
|
## How It Works
|
|
|
|
```
|
|
Customer pays / gets refund at POS
|
|
│
|
|
▼
|
|
Sum all paid pos.order amounts for this customer
|
|
│
|
|
▼
|
|
Fetch loyalty.program records where
|
|
multi_level_membership = True
|
|
(sorted by minimum_spend ASC)
|
|
│
|
|
▼
|
|
Find the highest tier where
|
|
minimum_spend ≤ total purchases
|
|
│
|
|
▼
|
|
Compare with current res.partner.membership_level_id
|
|
│
|
|
├── Different → Update to new level
|
|
└── Same → Do nothing
|
|
```
|
|
|
|
### Step-by-Step
|
|
|
|
1. **Trigger** — The module hooks into `action_pos_order_paid()`, which is called every time a POS order is finalized (both regular sales and refunds).
|
|
|
|
2. **Calculate Total Purchases** — Sums the `amount_total` field from all `pos.order` records with state `paid` or `done` for the customer. Refund orders naturally have a negative `amount_total`, so they reduce the total automatically.
|
|
|
|
3. **Fetch Loyalty Levels** — Retrieves all `loyalty.program` records where the `multi_level_membership` field (Boolean) is `True`, sorted by `minimum_spend` in ascending order.
|
|
|
|
4. **Determine Level** — Walks through the sorted programs and selects the **highest tier** where the customer's total purchases meet or exceed `minimum_spend`.
|
|
|
|
5. **Transfer Points** (If upgraded/downgraded) — Finds the customer's loyalty card for the old membership program. If it has points, transfers those points to the new program's loyalty card (creating one if it doesn't already exist), then resets the old card's points to 0.
|
|
|
|
6. **Compare & Update** — Checks the customer's current `membership_level_id` (Many2one to `loyalty.program`) on `res.partner`:
|
|
- If the level has **changed** → updates the field with the new program.
|
|
- If the level is the **same** → does nothing.
|
|
- If the customer doesn't meet **any** tier → clears the membership level.
|
|
|
|
## Dependencies
|
|
|
|
| Module | Purpose |
|
|
|--------|---------|
|
|
| `point_of_sale` | Provides `pos.order` model and POS transaction flow |
|
|
| `pos_loyalty` | Provides `loyalty.program` model |
|
|
|
|
## Example
|
|
|
|
Suppose you have three loyalty tiers configured:
|
|
|
|
| Loyalty Program | minimum_spend |
|
|
|----------------|----------------------|
|
|
| Bronze | 0 |
|
|
| Silver | 500,000 |
|
|
| Gold | 1,500,000 |
|
|
|
|
**Scenario — Upgrade:**
|
|
- Customer has accumulated **600,000** in total POS purchases.
|
|
- Current level: **Bronze**
|
|
- After a new purchase, total reaches **600,000** which is ≥ 500,000 (Silver) but < 1,500,000 (Gold).
|
|
- Result: Customer is upgraded to **Silver**.
|
|
|
|
**Scenario — Downgrade after refund:**
|
|
- Customer's total was **520,000** (Silver level).
|
|
- A refund of **50,000** brings the total down to **470,000**.
|
|
- 470,000 < 500,000 (Silver threshold), so customer drops back to **Bronze**.
|
|
|
|
## Module Structure
|
|
|
|
```
|
|
pos_loyalty_auto_level/
|
|
├── __init__.py
|
|
├── __manifest__.py
|
|
├── README.md
|
|
└── models/
|
|
├── __init__.py
|
|
└── pos_order.py # Core logic: overrides action_pos_order_paid()
|
|
```
|
|
|
|
## Installation
|
|
|
|
1. Place the `pos_loyalty_auto_level` folder in your Odoo `custom/` addons directory.
|
|
2. Update the apps list: **Settings → Apps → Update Apps List**.
|
|
3. Search for **"POS Loyalty Auto Level Update"** and click **Install**.
|
|
|
|
## Logging
|
|
|
|
The module logs membership level changes at `INFO` level and unchanged checks at `DEBUG` level. Check your Odoo server logs for entries from `odoo.addons.pos_loyalty_auto_level.models.pos_order`.
|
|
|
|
## License
|
|
|
|
LGPL-3
|