System Documentation: 7-Tier Loyalty System

1. Overview

This Shopify App implements a "Game of Chance" loyalty system. Instead of earning fixed points (like "1 point per ₹1"), customers earn a percentage voucher based on a random spin, weighted by probabilities.

2. Earning Logic (How Customers Get Vouchers)

The "Spin" Mechanics

When a customer pays for an order, the system automatically runs a "spin" for each product purchased.

If a customer buys 3 items, they get 3 separate spins (3 separate vouchers).

Tier	Voucher Value	Probability	Chance
Tier 1	1% Off	35%	Most Common
Tier 2	2% Off	25%	Common
Tier 3	3% Off	15%	Frequent
Tier 4	5% Off	12%	Lucky
Tier 5	10% Off	8%	Very Lucky
Tier 6	15% Off	3%	Rare
Tier 7	20% Off	2%	Jackpot

Example Scenario

Customer buys 3 items: A Shirt, A Pant, and A Hat.

Spin 1 (Shirt): Lands on Tier 3 -> Customer gets a 3% Voucher.
Spin 2 (Pant): Lands on Tier 5 -> Customer gets a 10% Voucher.
Spin 3 (Hat): Lands on Tier 1 -> Customer gets a 1% Voucher.

Global Budget Cap: To protect the business, there is a global limit (Default: ₹1,00,000). If the estimated value of issuing a new voucher exceeds this limit, the system effectively stops awarding high-tier vouchers.

3. Redemption Logic (Lifecycle)

The system tracks the full lifecycle of a coin:

Active: The customer has won the coin but hasn't used it yet.
Reserved: The customer has selected the coin in their cart. A Shopify Discount Code (e.g., LOYALTY-XY...) is generated and locked to them.
Redeemed: The customer successfully completed the order using the discount. The coin is marked as used.

Stacking Rules

Stacking Allowed: Customers can combine multiple vouchers.
Max 20% Limit: The total discount can NEVER exceed 20%.
No Partial Use: Vouchers must be used fully.

Example of "Smart Stacking"

User has: [10% Voucher] and [15% Voucher].

Scenario:

If they check the 10% box, they have 10% total discount.
The system will then DISABLE the 15% box (because 10+15 = 25%, which is > 20%).
The user must uncheck 10% if they want to use the 15% one.

4. Validity & Expiration

To encourage active participation, all vouchers have a validity period.

Policy: Unused coins expire automatically after 30 Days from the date of issuance.

5. Frontend Integration

The Widget (coin-widget.js) is injected into the store theme.

Account Page: Displays a "My Voucher Collection" grid showing all earned tiers.
Cart Page & Drawer: Works in both the standard Cart Page and the AJAX Cart Drawer.
Post-Purchase Popup: A "Celebration Modal" appears on the Thank You page when a new reward is earned.
Checkout Page: The generated Discount Code (e.g., LOYALTY-A1B2...) is automatically applied.

6. Mystery Rewards (New!)

We have introduced a "Pending Reward" system to incentivize payments.

The Hook: "You have won a Mystery Reward! Complete payment to reveal it."

How it Works

Order Placed: A blurred "Mystery Card" appears in the customer's wallet immediately. It is marked as PENDING.
Payment Confirmed: Once payment is successful (e.g., Prepaid or COD Confirmed), the card Unblurs/Reveals.
Ready to Use: The reward becomes Active and can be used on the next purchase.

Note: Pending rewards cannot be redeemed. They must be "unlocked" by completing the payment for the order that generated them.

7. Admin Dashboard

Located at /admin.

Budget Control: View how much of the ₹1 Lakh limit has been consumed. Update the limit dynamically.
Campaign Management: Start new campaigns with an optional "Max Orders" cap.
- Metrics: Track "Orders Success" (Redeemed Count) and "Sales Generated" in real-time.
- View Details: Click on any campaign to see the Full Lifecycle of coins (Active, Reserved, Redeemed, Expired) along with Reservation Codes.
Manual Credit: Manually issue a specific Tier Voucher (1-7) to a Customer ID.
- Blue "M" Flag: Manually added vouchers are selected with a blue tag.
- Filtering: Use the "Filter: Manual" button to segregatemanual issues.

8. Developer API (External Integration)

You can use these endpoints to build custom history pages or mobile app integrations.

GET /coins/history

Fetch a list of past transactions (redeemed, expired, revoked) for a specific customer.

                GET https://tierloyaltycommon.task19.com/api/coins/history?customer_id=123456789&shop=your-store.myshopify.com
            

Response Example:

{
    "customer_id": "123456789",
    "history": [
        {
            "id": 101,
            "coin_type": "Gold",
            "coin_value_percentage": 15,
            "status": "redeemed",
            "reservation_code": "LOYALTY-A1B2C3",
            "updated_at": "2024-02-12T10:00:00.000000Z",
            "created_at": "2024-02-01T10:00:00.000000Z"
        },
        {
            "id": 102,
            "coin_type": "Bronze",
            "coin_value_percentage": 5,
            "status": "expired",
            "updated_at": "2024-01-15T10:00:00.000000Z"
        }
    ]
}

9. Troubleshooting & Authorization

Critical: "Invalid API Key" Error

If the widget says [API] Invalid API key or Token Lacks Permission, it means the App's Access Token is stale or missing permissions.

How to Fix (The "Re-Auth" Cycle):

Go to Shopify Admin > Apps.
Click on Tier Based Loyalty (This triggers a token refresh).
If asked to Update App or Grant Permissions, click Update/Allow.
The error on the storefront will resolve immediately.

Self-Healing Diagnostics

You can check the server's health status at any time by visiting:

https://tierloyaltycommon.task19.com/api/coins/debug-token?shop=YOUR_SHOPIFY_DOMAIN

api_check_shop: SUCCESS = Token is working.
api_check_pricing_access: SUCCESS = App can create discounts.