Projects:LoyaltyManagement/Functional Guide
Contents |
Module Definition
- Name: Loyalty Management for Retail
- Version: 1.0.0.
- Java package: org.openbravo.retail.loyalty
- Description: Automatic generation of the production of the products before processing the order
- Language: En_US
- License: Commercial
- License Text: Copyright (C) 2014 Openbravo S.L.U. Licensed under the Openbravo Commercial License version 1.0. You may obtain a copy of the License at http://www.openbravo.com/legal/OBCL10/BasicLicense.html
- Author: Openbravo S.L.U.
This module will be dependant of
- Web POS
Earning and accumulating loyalty points
Loyalty points are accumulated by customers when buying goods according to predefined rules. To accumulate points the customer must be identified first as participant of the loyalty program that belongs the store.
Data structure
The rules that defines how points are accumulated is a new table with the following structure. There is also a window that edits the data of the rules.
- Loyalty Program (Header):
- Search Key. Not null. Search key of the loyalty program.
- Name. Not null. Name of the loyalty program
- Image ?
- Business partner. Business partner owner of the loyalty program.
- Required amount. The minimum amount of the total of the ticket needed accumulate points.
- Round points (By receipt line, By receipt total)
- Round type (UP, DOWN, CEILING, FLOOR, HALF_UP, HALF_DOWN, HALF_EVEN)
- Point Accumulation Rules (Level 1)
- Organization
- Start Date. Not null. The start date from this rule is applied.
- End Date. The end date up until this rule is applied. If null then there is no end date.
- Product. The product this rule applies. If null then the rule applies to all products.
- Activity: Reference to the Activity table.
- Rate: Amount needed to earn one loyalty point. (Negative if the product accumulates less points than the generic rule)
Activities is a new auxiliary table with the following structure. There is also a window to edit the activities data.
- SearchKey. Not null. Search key of the activity.
- Name. Not null. Name of the activity.
- Business Partner. Not null. Reference to Business partner that promotes this activity.
The organization window must have a new tab at level 1 with a list of the Loyalty programs available for that store. Take into account that Web POS will only support one loyalty program.
Payment methods of POS Terminal Types have a configuration field to define whether the receipt accumulates points or not if it is used to pay totally or partially the receipt. For example, a receipt does not accumulate points if is paid with store notes or other payment methods the store does not want to accumulate points if it is used...
Order header has a new optional field that defines the membership ID of the loyalty program of the customer. This membership ID is not managed by Openbravo and is not related to the business partner of the receipt in any case. This field must appear in the orders window.
The points accumulated is a new table where it is registered the points accumulated, It has the following structure:
- Loyalty program. Reference to the loyalty program.
- Order line. Reference to the order line that accumulated the points.
- Activity. Reference to the Activity of the rule applied
- Points. Points accumulated as a total of all the rules applied by order line and activity.
There is also a read only window that allows to inspect the accumulated points and allows the user to filter using the standard Openbravo filters. This window must show the following information for each record:
- Loyalty program
- Membership ID of the customer
- Store name
- Document no
- Order date
- Product name
- Quantity
- Product price
- Line total
- Activity name
- Points accumulated
It also must show the total sum of the points shown in the table view.
Logic to apply rules
Points are accumulated line by line and all the valid rules that are applied to an specific line are the following:
- The organization belongs to the Store organization or a parent organization. This applies rules in a hierarchical way. QUESTION: Does this make sense with the organization of rules by loyalty program and version?
- The current date is between the start date and end date of the version.
- The product defined in the rule is null or equal to the product line.
Points are not accumulated if the total of the ticket is less than the Required Amount configuration value defined at loyalty program level. Points are not accumulated if there is no membership ID of the loyalty program of the customer registered. Points are not accumulated if it is paid totally or partially with a payment method configured as it does not accumulate points. For example loyalty points or store notes.
The points are calculated when closing the receipt, as it is needed to have the points accumulated in a sale just before sending the ticket to the backend and printing it.
Membership ID request
In order to accumulate points the is needed to request the membership ID to the customer. This action is lauched when tapping on the total to go to the payment panel and a menu option. When executing the action a dialog is displayed. In this dialog the cashier enters the membership ID manually or reading the customer membership card. It can be read using a barcode scanner or a magnetic card reader. This card reader must be connected as an HID (keyboard) to work properly with Web POS.
The javascript function that parses the entry read by the barcode scanner / magnetic card reader and returns whether the entry is valid or not and the membership ID must be overwritable by a new module in order to allow different functions for different loyalty programs. The javascript function must be registered using the search key of the loyalty program.
Points accumulated printed in the receipt
The receipt prints the total of the points accumulated grouped by activity. For example:
| Loyalty membership ID | XXXX |
|---|---|
| Activity A points | 10 |
| Activity B points | 20 |
| Total points | 30 |
Server side process
The server side process that registers the points accumulated is a new Order Loader Hook. This process must be responsible of storing the Customer loyalty program ID in the order, storing in the accumulated table the information of the points accumulated and invoking a registered interface sending the information of the accumulated points. This implementation depends on the loyalty program selected by the store
Request of accumulated points
A customer can request the accumulated points in the membership program to the cashier. The accumulated points are not managed by Openbravo but it must be accesible from the Web POS user interface.
This functionality is only available when Web POS is in online mode.
Membership ID request
This action is lauched using a button or a menu option that displays a dialog. In this dialog the cashier enters the membership ID manually or reading the customer membership card and it is very similar to the dialog that registers the membership ID to accumulate points.
Then a request is sent to the backend with the membership ID and the backend invokes a registered interface with this membership ID and returns the accumulated points and other membership information. This implementation depends on the loyalty program.
The web service will implement a timeout. The request will be considered as failed if the web service spends more than 20 seconds to deliver a response.
Printing the accumulated points
When the Web POS receives the data a receipt is printed with the membership information and the accumulated points. The template that defines the receipt printed with the accumulated points must be configurable the same way the rest of receipt templates are.
Redemtion
Customers can redeem the accumulated points of a loyalty program by goods. The value in cash of a loyalty point is defined as Loyalty Program level. This action will be available only when the POS is online.
Data structure
In the Loyalty Program there is a new tab at level 1 for the redeem factors:
- Point Redeemtion rates
- Start Date. Not null. The start date from this rule is applied.
- End Date. The end date up until this rule is applied. If null then there is no end date.
- Redeem Factor. The amount value for one loyalty point.
The points redeemed is a new table where it is registered the points redeemed, It has the following structure:
- Loyalty program. Reference to the loyalty program.
- Order. Reference to the order that redeemed the points.
- Points. Points redeemed
There is also a read only window that allows to inspect the redeemed points and allows the user to filter using the standard Openbravo filters. This window must show the following information for each record:
- Loyalty program
- Membership ID of the customer
- Store name
- Document no
- Order date
- Order total
- Points redeemed
Membership ID request
The action that redeems loyalty points will appear as a payment method in the total panel but internally it will be not a payment method.
If the action to redeem loyalty points is launched (or a payment method marked as not accumulate points is selected) and there is already added a membership ID entered to accumulate points, a message will appear explaining that it is not allowed to accumulate points. And allowing the cashier to continue or cancel the action.
If accepted not to accumulate points a dialog will appear. In this dialog the cashier enters the membership ID manually or reading the customer membership card and it is very similar to the dialog that registers the membership ID to accumulate points.
Then a request is sent to the backend with the membership ID and the backend invokes a registered interface with this membership ID and the points to redeem. This web service will returns with te result if the operation is acepted or not. For example if it is not allowed to redeem less than 1000 points. The webservice will handle this exception and return the result and a message with the error.
The web service will implement a timeout. The request will be considered as failed if the web service spends more than 20 seconds to deliver a response.
Once the payment with loyalty points, the business partner of the order will change to the Business partner that is the owner of the loyalty program used.
An order paid totally or partially with loyalty points cannot be invoiced. The same in the cashup process, orders paid totally or partially with loyalty points are not invoiced.
The Payment Method used to redeem loyalty points is not registered as a real payment in the order stored in the backend and the order will be left unpaid, totally or partially. In the cashup process also Payment methods used to redeem loyalty points will not be considered, and in general in any other process that uses payment methods.
Server side process
The server side process that registers the points redeemed is a new Order Loader Hook. This process must be responsible of storing the Customer loyalty program ID in the order, storing in the redeemed table the information of the points and invoking a registered interface sending the information of the accumulated points. This implementation depends on the loyalty program selected by the store.