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).

Example Scenario

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.

4. Validity & Expiration

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

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 is automatically applied.

6. Mystery Rewards (New!)

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

How it Works

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

7. Admin Dashboard

Located at /admin.

• Budget Control: View how much of the limit has been consumed. Update the limit dynamically.
• Campaign Management: Start new campaigns with an optional "Max Orders" cap. Track "Orders Success" and "Sales Generated" in real-time.
• Manual Credit: Manually issue a specific Tier Voucher (1-7) to a Customer ID.

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 for a specific customer.

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"
        }
    ]
}
                

9. Troubleshooting & Authorization

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):

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