Points for Rewards

1. What this page does

The Points for Rewards page allows administrators to manage physical and premium items offered in the lobby point shop. Administrators can create new reward items, upload product images, set point costs, manage inventory stock, configure redemption limits per player, and control the display order in the shop. In addition, administrators can review incoming reward requests, approve requests once the items have been delivered to players, or refuse requests to automatically refund points and return inventory stock.

Related views in the system include:

• Rewards tab — Main reward items list and catalog settings.
• Create new reward form — Form to add a new reward item.
• View / edit reward page — Screen to review or update reward settings.
• Report & history tab — Analytics summary and reward request history logs.

---

2. Before you start

• Required Permissions:
  • You must have the 'Points for rewards' permission in Roles to view the reward catalog, change shop order, and create or edit rewards.
  • You must have the 'Points for rewards - report and history' permission in Roles to access reports and approve or refuse reward requests.
• Prerequisites:
  • Reward Picture: Every reward requires an image. Prepare a PNG, JPG, or WEBP file up to 5 MB (a square 512x512 image is recommended).
  • Inventory Stock: Decide on available inventory stock or choose unlimited.
• Key Rules for Reward Requests:
  • When a player submits a request in the lobby shop, points are deducted and inventory stock decreases immediately, creating a request in the Waiting state.
  • Physical rewards are not delivered automatically. Administrators or support staff must fulfill the delivery and manually click Approve.
  • If a reward cannot be delivered (e.g. out of stock), click Refuse and provide a reason. The system will automatically return points to the player and restore the item's stock count.

---

3. Screen layout

The page is organized into two primary tabs:

1. Rewards Tab:
   • Add Reward Button: Located at the top right, opens the creation form.
   • Status Tabs and Filter Bar: Filter tabs for All, Open, Closed, and Deleted, along with keyword search and date/admin filters.
   • Rewards Table: Displays reward thumbnails, shop order numbers, point costs, remaining stock, exchange counts, status switches, and row actions.
2. Report & History Tab:
   • Summary Metric Cards: Standing requests, unique players, points paid, approved requests, and waiting requests.
   • Trend and Share Charts: Daily/hourly request trend line chart and a donut chart of top requested rewards.
   • Breakdown Tables: Breakdown of rewards requested and the top 10 most active claimant players.
   • Request Status Filter Tabs: Switch between All, Waiting, Approved, and Refused.
   • Reward Requests Table: Full history of requests with Approve and Refuse action buttons for pending items, plus a CSV export button.

---

4. Search and filters

Filters on Rewards Tab

Field / Filter	Type	Options / How to use	Result
Search...	Text input	Type reward title (Thai/English) or point cost	Filters table to matching reward items.
Status Tabs	Tab buttons	Select: All, Open, Closed, or Deleted	Filters catalog by active visibility status.
Created Range	Date range picker	Select start and end creation dates	Shows rewards created within the date window.
Updated Range	Date range picker	Select start and end update dates	Shows rewards modified within the date window.
Created By	Admin typeahead	Type admin name to select account	Shows items created by the selected administrator.
Updated By	Admin typeahead	Type admin name to select account	Shows items last edited by the selected administrator.
Clear	Button	Press Clear	Resets all filters and displays the full catalog.

Filters on Report & History Tab

Field / Filter	Type	Options / How to use	Result
Period	Quick preset buttons	Choose: Today, 7 days, 30 days, or Custom	Updates summary stats, charts, and breakdown tables.
Search requests...	Text input	Type player username, reward title, or points	Filters rows in the reward requests table below.
Request Status	Tab buttons	Select: All, Waiting, Approved, or Refused	Filters requests by administrative review status.
Exchanged Range	Date range picker	Select redemption date range	Filters requests by the date they were submitted.
Handled By	Admin typeahead	Type admin username	Shows requests approved or refused by the specified administrator.

---

5. Data tables

1. Rewards Table (Rewards Tab)

Column	What you see	Meaning	Badge or Symbol
Order	Order number in shop with up/down arrows	Display position seen by players in the lobby	• Circle badge: Click to open reposition modal • Up/down arrows: Move position step by step
Item	Image thumbnail, bold Thai name, and English name	Reward details and visual preview	Square image thumbnail; click title to edit
Point Cost	Number of points (e.g. 1,500 points)	Points required to redeem 1 piece	Right-aligned number
Stock	Inventory status badge	Stock count remaining in inventory	• Gray: Unlimited or 12 left • Orange: 5 or fewer left (low stock warning) • Red: Out (redemption disabled)
Limit	Limit per player badge	Redemption frequency allowance	• Gray: No limit • Blue: Per day / Over the membership
Exchanged	Completed exchanges count, plus waiting count	Redemption statistics for this item	• Normal number: Completed count • Orange chip: 3 waiting
Last Edited	Date, time, and admin updater name	Audit trail of the last modification	Standard date and username
Status	Toggle switch or Deleted badge	Shop visibility toggle	• Green switch: Open • Gray switch: Closed • Gray badge: Deleted
Actions	3-dots action menu	Action triggers	Options: Details, Edit, or Delete

2. Reward Requests Table (Report & History Tab)

Column	What you see	Meaning	Badge or Symbol
Exchanged	Date and time (e.g. 21/10/2026, 16:30)	Timestamp when the player submitted the request	Standard date/time format
Player	Player username (e.g. somying01)	Player account requesting the reward	Bold username text
Item	Thumbnail image and reward title	Reward item requested	Image thumbnail and text
Points	Points deducted (e.g. 2,000)	Points deducted from player's balance	Right-aligned number
Status	Request status badge	Current review status	• Orange (Waiting): Pending fulfillment • Green (Approved): Handed over to player • Gray (Refused): Refused; points returned
Handled By	Admin name, date, and refusal reason	Record of the admin who answered the request	Username, timestamp, and optional reason note
Actions	Approve and Refuse buttons	Decision buttons (visible on waiting requests)	• Default button: Approve • Destructive button: Refuse

---

6. Step-by-step

1. Adding a new reward item

1. Navigate to Activities > Points for rewards in the Rewards tab.
2. Click Add reward at the top right.
3. Under What players see:
   • Enter Name (Thai) (required, e.g. เสื้อยืดลิมิเต็ด ลายพิเศษ).
   • Enter Name (English) (optional, e.g. Limited Edition T-Shirt).
   • Enter Description (Thai) and Description (English) (plain text up to 20,000 characters).
   • Under Reward picture, click Choose picture and upload an image (PNG, JPG, or WEBP up to 5 MB).
4. Under Cost and reward:
   • Point cost: Enter required points (integer >= 1).
   • Stock: Enter available quantity (e.g. 50), or leave blank for Unlimited.
5. Under Limit per player:
   • Select limit type: No limit, Per day, or Over the membership.
   • If limited, enter the allowed count in Times (integer >= 1).
6. Under Status on the right side, verify the switch is set to Open.
7. Click Save in the bottom action bar.

2. Reordering rewards in the shop

1. In the Rewards table, locate the Order column.
2. You can reorder items in two ways:
   • Arrow buttons: Click Move up or Move down to shift position one step.
   • Direct reposition dialog: Click the numbered circle badge to open the Place in the shop dialog, choose a target position number, and confirm.
3. Other rewards shift automatically to make room. The new order immediately updates in the player lobby.

3. Approving a reward request

1. When a player requests a physical reward, open the Report & history tab.
2. Click the Waiting status filter tab to isolate pending requests.
3. Once customer support or warehouse staff have physically handed over or shipped the reward, click Approve on the request row.
4. In the Approve this request? confirmation prompt, review the player username and reward title, then confirm.
5. The status changes to Approved (Green). This action is permanent and cannot be undone.

4. Refusing a reward request (Refunding points and stock)

1. If the item cannot be fulfilled (e.g. out of stock or unreachable address), locate the request under the Waiting filter.
2. Click Refuse on the request row.
3. The Refuse this request? dialog opens.
4. Enter a refusal explanation in the Reason field (required, e.g. Out of stock or Invalid delivery address).
5. Confirm refusal.
6. The system immediately executes two actions automatically:
   • Refunds the deducted points back to the player's wallet.
   • Restores 1 unit back to the reward's inventory stock.
   • Displays the refusal reason to the player in their lobby history.

5. Deactivating or deleting a reward item

1. Before deleting a reward, ensure no requests remain in the Waiting status. If any exist, approve or refuse them first.
2. In the rewards table, toggle the Status switch to Closed (Gray).
3. Click the 3-dots action menu on that row and select Delete.
4. Confirm deletion in the prompt. The item moves to the Deleted tab.

---

7. Edit / Add forms

Form fields for creating and editing reward items include:

Section	Field	Required?	What to enter	Rules & Constraints
What players see	Name (Thai)	Required	Reward title in Thai	Max 255 characters, must be unique
	Name (English)	Optional	Reward title in English	Max 255 characters (falls back to Thai name if omitted)
	Description (Thai)	Optional	Plain text description in Thai	Max 20,000 characters
	Description (English)	Optional	Plain text description in English	Max 20,000 characters
	Reward picture	Required	Product photo or graphic	PNG, JPG, or WEBP up to 5 MB (512x512 square recommended)
Cost and reward	Point cost	Required	Points required for 1 item	Whole number >= 1
	Stock	Optional	Inventory count	Whole number >= 0 (leave blank for unlimited)
Limit per player	Limit kind	Required	Select: No limit, Per day, Lifetime	Choose 1 option
	Times	Required (if limited)	Maximum allowed redemption times	Whole number >= 1
Status Card (Right)	Place in shop	Required (when editing)	Display order position in catalog	Number from 1 to total reward count
	Status	Required	Visibility switch in shop	Open (Green) or Closed (Gray)

---

8. Popups and dialogs (Popup / Modal)

1. Place in the Shop Dialog (Move to Dialog)

• When it opens: When clicking the circular order badge in the Order column.
• What you see: A selector listing all available shop position slots.
• What to do: Select the desired destination number and confirm.
• Result: Repositions the reward and shifts other items accordingly.

2. Approve Request Confirmation Dialog

• When it opens: When clicking Approve on a waiting request.
• What you see: Reward name, player username, and confirmation text stating the action cannot be undone.
• What to do: Verify physical delivery has occurred, then click Approve.
• Result: Request status becomes Approved.

3. Refuse Request Dialog

• When it opens: When clicking Refuse on a waiting request.
• What you see: Reward name, points to be refunded, and a mandatory Reason textarea.
• What to do: Enter the reason (e.g. Out of stock) and click Refuse.
• Result: Cancels request, refunds points to the player, and returns 1 item to stock.

4. Delete Reward Confirmation Dialog

• When it opens: When selecting Delete on a closed reward item.
• What you see: Warning prompt stating the reward will leave the shop catalog.
• What to do: Click the red Delete button to confirm.
• Result: Moves reward to the Deleted archive.

5. Version Conflict Dialog

• When it opens: When saving a reward that was updated by another administrator simultaneously.
• What you see: Outdated version alert.
• What to do: Click Load latest to fetch latest changes, then re-apply edits.
• Result: Prevents concurrent edit overwrites.

---

9. Statuses and badges

1. Reward Catalog Statuses

Status Badge	Color	Meaning	Next Action
Open	Green	Item is active and visible in the lobby shop.	Normal operational state.
Closed	Gray	Item is hidden from the lobby shop; order position retained.	Toggle switch to open when ready.
Deleted	Gray	Item was permanently archived.	Read-only audit log.
5 or fewer left	Orange	Stock is running low.	Restock inventory if additional units are available.
Out	Red	Inventory stock reached 0; redemptions disabled in lobby.	Restock inventory or close the item.

2. Reward Request Statuses (Report & History Tab)

Status Badge	Color	Meaning	Next Action
Waiting	Orange	Player submitted request; points and stock reserved.	Staff must review and click Approve or Refuse.
Approved	Green	Staff confirmed physical delivery of the item.	Fulfilled terminal state.
Refused	Gray	Request was refused; points and stock returned.	Cancelled terminal state.

---

10. Frequently asked questions / Troubleshooting

• Why does the system prevent deleting a reward with "Requests for this reward still wait for an answer"?
  • A reward cannot be deleted while unresolved requests exist. Navigate to Report & history, filter by Waiting, and approve or refuse all pending requests for that item before attempting deletion.
• Why does saving a reward fail with "A reward needs a picture"?
  • Reward items strictly require an uploaded image file (PNG, JPG, or WEBP up to 5 MB). Upload a valid picture in the image upload field before saving.
• Does the player get their points back immediately when a request is refused?
  • Yes. As soon as you confirm refusal, the system immediately credits the points back to the player's wallet and increments the item's stock count by 1.
• How does catalog reordering affect the lobby display?
  • Position 1 appears first at the top-left of the player's reward store. Adjust popular or featured items to lower order numbers so players see them first.