=== LoyaltyNova for WooCommerce ===
Contributors: sandipdeveloper
Tags: woocommerce loyalty, loyalty points, customer rewards, woocommerce rewards, points and rewards
Requires at least: 5.8
Tested up to: 7.1
Requires PHP: 7.4
WC requires at least: 6.0
WC tested up to: 8.7
Stable tag: 1.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Complete loyalty rewards for WooCommerce. Reward purchases and referrals with points redeemable for checkout discounts or digital gift cards.

== Description ==

**LoyaltyNova for WooCommerce** provides a customer retention and rewards program designed specifically for WooCommerce stores. Increase your store's customer lifetime value (LTV) and repeat sales by rewarding customers with loyalty points for their completed orders and referrals. Accumulated points can be redeemed directly at checkout for cart discounts or exchanged for digital WooCommerce gift cards.

Built with performance, security, and scalability in mind, the plugin is fully compatible with WooCommerce High-Performance Order Storage (HPOS) and WooCommerce Cart & Checkout Blocks.

### Core Features

*   **Configurable Points Earning:** Award points based on spend ratios (e.g., $1 spent = 1 point) with role-based eligibility controls.
*   **Referral Bonus Rewards:** Automatically award bonus points to existing customers when referred users place successful orders.
*   **Checkout Points Redemption:** Customers can apply points directly on the cart and checkout pages for instant order discounts.
*   **Digital Gift Card Coupons:** Customers can convert accumulated points into shareable WooCommerce coupon codes.
*   **Membership Tier Progression:** Create custom VIP membership tiers (e.g., Silver, Gold, Platinum) with automatic points multipliers for top spenders.
*   **Customer "My Rewards" Dashboard:** A responsive rewards portal integrated directly into the WooCommerce My Account area.
*   **Automated Points Expiration:** Automatically expire inactive customer points after a configurable period via daily cron tasks.
*   **Automated Email Notifications:** Customizable HTML email notifications for earned points, redeemed points, expirations, gift card issuance, and referral bonuses.
*   **Live Email Preview Shell:** In-admin modal preview to test email template design before sending messages to customers.
*   **Admin Points Ledger Adjustments:** Manually add or deduct points from individual customer balances with audit notes.
*   **Store Analytics & Transactions:** Monitor global store metrics, active liabilities, and search individual transaction logs.
*   **System Integrity Diagnostics:** Run automated recalculations on user balances to verify ledger consistency and detect anomalies.
*   **Historical Order Migration:** Process existing historical WooCommerce orders to award retroactive loyalty points.

### Performance & Compatibility

*   **100% HPOS Compatible:** Full compatibility with WooCommerce High-Performance Order Storage (`custom_order_tables`).
*   **Cart & Checkout Blocks Ready:** Native integration with WooCommerce Block-based checkout workflows.
*   **Custom Database Architecture:** Uses 3 dedicated, indexed database tables (`wp_loyalty_points`, `wp_loyalty_transactions`, `wp_loyalty_gift_cards`) for high-speed balance lookups without bloating `usermeta`.

== Installation ==

1. Upload the `loyaltynova-for-woocommerce` folder to the `/wp-content/plugins/` directory, or install directly through the WordPress Plugins dashboard.
2. Activate the plugin through the **Plugins** screen in WordPress.
3. Navigate to **Loyalty Rewards > Loyalty System Settings** in your WordPress admin sidebar to configure your earning rates and allowed user roles.
4. (Optional) Configure membership tier multipliers under **Loyalty System Settings**.
5. (Optional) Configure customer dashboard display options under **Loyalty Rewards > Frontend Rewards Settings**.
6. (Optional) Customize automated notifications under **Loyalty Rewards > Email Notifications**.
7. (Optional) Define gift card coupon prefixes and length under **Loyalty Rewards > Gift Card Settings**.

== Configuration ==

Navigate to the top-level **Loyalty Rewards** admin menu to manage your store's loyalty system across 7 dedicated settings screens:

*   **Loyalty System Settings (`lpfw-settings`):** Set earning rates, points redemption value, minimum/maximum order limits, allowed customer roles, membership tiers, points expiration rules, and historical order migration.
*   **Loyalty Transactions (`lpfw-transactions`):** View, search, and filter the global storewide transaction ledger.
*   **Loyalty Analytics (`lpfw-analytics`):** Track total points earned, redeemed points, total active balance liabilities, generated gift cards, and customer account summaries.
*   **Frontend Rewards Settings (`loyalty-frontend-settings`):** Toggle section visibility on the customer dashboard and set pagination limits.
*   **Email Notifications (`loyalty-email-settings`):** Enable email notifications, customize subject lines, hero banners, button text, and preview HTML email templates in-admin.
*   **Gift Card Settings (`loyalty-giftcard-settings`):** Configure gift card coupon code prefixes, code length, and email template branding.
*   **Diagnostics (`loyalty-diagnostics`):** Run full system integrity scans to recalculate user balances against historical transaction logs.

== Customer Experience ==

When enabled, customers experience a seamless rewards flow:

1. **Earning Points:** Customers earn points automatically when an order reaches `completed` or `processing` status based on store rules and tier multipliers.
2. **Referrals:** Existing customers share referral links or codes to earn bonus points when referred users place orders.
3. **My Account Dashboard:** Customers navigate to **My Account > Rewards** to view their active point balance, current membership tier, transaction history, pending points, and gift card generator.
4. **Checkout Redemption:** Customers enter the number of points to redeem directly inside the Cart or Checkout redemption box for an instant order discount.

== Frequently Asked Questions ==

= Does this plugin require WooCommerce? =
= Does this plugin require WooCommerce? =
Yes, LoyaltyNova for WooCommerce is a WooCommerce extension and requires an active installation of WooCommerce (v6.0 or higher).

= How do customers earn points? =
Customers earn points automatically on completed orders based on your configured conversion rate (e.g., $1 = 1 point). If a customer belongs to a higher membership tier, their earned points are multiplied automatically.

= How do customer membership tiers work? =
Tiers can be configured under **Loyalty System Settings**. Upgrades occur automatically based on lifetime points earned by the customer, applying custom point multipliers to future purchases.

= Can customers redeem points at checkout? =
Yes. Customers can enter points on the Cart or Checkout pages to generate an immediate order discount. You can also specify minimum and maximum points limits per redemption.

= How does gift card creation work? =
Customers can exchange accumulated points for a digital gift card inside their **My Account > Rewards** dashboard. The plugin creates a unique WooCommerce coupon code (e.g., `GC-A2B4C6D8`) valid for single-use checkout discounts.

= How do referral rewards work? =
Store owners can configure referral bonus points under global settings. When a new customer completes an order via a referral link, the referrer receives bonus loyalty points automatically.

= What happens when an order is refunded or cancelled? =
When an order status changes to `refunded` or `cancelled`, points earned from that order are automatically reversed and deducted from the customer's balance. If points were redeemed on the order, they are credited back to the customer.

= Can administrators manually adjust points? =
Yes. Under **Loyalty Rewards > Loyalty Analytics**, click **Adjust** on any customer row or open **Customer Detail** to manually add or deduct points with a required audit reason.

= What email notifications are included? =
The plugin includes automated HTML emails for:
*   Points Earned
*   Points Redeemed
*   Points Expired
*   Gift Card Created
*   Referral Bonus

= Can I preview email templates before sending? =
Yes. Under **Loyalty Rewards > Email Notifications**, click the **Preview Template** button on any notification card to open an in-admin modal preview.

= Is High-Performance Order Storage (HPOS) supported? =
Yes. LoyaltyNova for WooCommerce includes explicit compatibility declaration for WooCommerce HPOS (`custom_order_tables`).

= Are WooCommerce Cart and Checkout Blocks supported? =
Yes. The plugin is tested and compatible with WooCommerce Block checkout components.

= Where is customer loyalty data stored? =
Loyalty transaction records are stored in 3 custom indexed database tables (`{$wpdb->prefix}loyalty_points`, `{$wpdb->prefix}loyalty_transactions`, `{$wpdb->prefix}loyalty_gift_cards`). Account balance and tier summaries are also cached in user meta (`loyalty_points_balance`, `loyalty_user_tier`).

= What happens when I uninstall the plugin? =
Uninstalling the plugin via the WordPress admin screen removes all 3 custom database tables, all plugin option settings in `wp_options`, user meta records, and order meta records to ensure a clean database environment.

== Screenshots ==

1. **Loyalty System Settings:** Configure global conversion rates, allowed user roles, membership tier multipliers, and expiration rules.
2. **Loyalty Analytics:** Track global points issued, redeemed totals, active balances, gift cards count, and customer accounts.
3. **Loyalty Transactions Ledger:** View, search, and filter storewide transaction records with status badges.
4. **Frontend Rewards Settings:** Control dashboard visibility, section toggles, and table pagination limits.
5. **Email Notifications:** Customize subject lines, hero banner images, call-to-action buttons, and preview email templates.
6. **Gift Card Settings:** Define gift card coupon prefixes, code length, and recipient email branding.
7. **Customer Detail View:** Inspect individual customer wallet overview, transaction ledger, manual points adjustments, and tier overrides.
8. **Customer Rewards Dashboard:** Responsive customer dashboard integrated into the WooCommerce My Account area.

== Changelog ==

= 1.0.0 =
*   Initial Production Release: Complete enterprise-grade loyalty points engine for WooCommerce.
*   Feature: Points earning based on order spending ratios and allowed user roles.
*   Feature: Points redemption at cart and checkout for dynamic order discounts.
*   Feature: Digital gift card creation converting points to single-use WooCommerce coupons.
*   Feature: Membership tier progression with automatic lifetime points upgrades and multipliers.
*   Feature: Referral bonus point system rewarding existing customers for new order referrals.
*   Feature: Automated daily expiration cron task purging inactive points.
*   Feature: Automated HTML email notifications with in-admin modal email template preview.
*   Feature: Comprehensive Store Analytics and global Transaction Audit Ledger.
*   Feature: Admin Manual Points Adjustments with mandatory audit notes.
*   Feature: System Integrity Diagnostics recalculating user balances against transaction ledgers.
*   Feature: Historical WooCommerce Order Migration tool.
*   Architecture: Custom indexed database schema (`wp_loyalty_points`, `wp_loyalty_transactions`, `wp_loyalty_gift_cards`).
*   Compatibility: Declarative support for WooCommerce High-Performance Order Storage (HPOS).
*   Compatibility: Built-in integration with WooCommerce Cart and Checkout Blocks.
*   UI/UX: Modern SaaS-grade WooCommerce admin design system with full accessibility support.

== Upgrade Notice ==

= 1.0.0 =
Initial release of LoyaltyNova for WooCommerce.
