Omnify Customer Rewards for WooCommerce Plugin Documentation
Version: 1.0.2
Updated: 2026-05-31

1. Overview
Omnify Customer Rewards for WooCommerce is a loyalty plugin that allows stores to award points for purchases and daily check-ins, let customers redeem points for discounts, and run a spin wheel reward campaign.

2. Core Features
- Purchase rewards based on configurable points ratio
- Daily check-in points for logged-in customers
- Product-level custom points override
- Points redemption with max redemption percentage
- Customer points display on My Account and checkout/cart areas
- Points history for customers and admins
- Admin tools to increase/decrease user points
- Refund/cancel points adjustment (optional)
- Spin wheel rewards with one-spin-per-completed-order rule
- Multi-currency-ready conversion hook support

3. Requirements
- WordPress 5.0+
- WooCommerce 8.0+
- PHP 8.0+

4. Installation
1. Upload the plugin folder to:
   /wp-content/plugins/omnify-customer-rewards-woocommerce/
2. Activate the plugin in WordPress Admin > Plugins.
3. Open WooCommerce > Settings > Omnify Customer Rewards.
4. Configure point and spin options.

5. Settings (WooCommerce > Settings > Omnify Customer Rewards)
- Enable Daily Check-In Points
- Daily Check-In Points
- Points per Purchase
- Value per 1000 points
- Max Redemption Percentage
- Decrease Points on Refund/Cancel
- Enable Spin Wheel
- Minimum Order Amount to Spin
- Spin Wheel Values (comma-separated)

6. How Points Work
6.1 Earn points from purchases
- Earned points = order total (base currency) x points-per-purchase ratio.

6.2 Product-specific points
- If product meta "Points for this product" is set, that value is used for that product.

6.3 Redeem points
- Point value is calculated from "Value per 1000 points".
- Redemption is capped by "Max Redemption Percentage".

6.4 Refund behavior
- If enabled, points are reduced for refunded/cancelled orders.

7. Spin Wheel Rules
- Visible on My Account when enabled.
- User must have an eligible completed order (and meet minimum order threshold).
- User can spin only once per eligible completed order.
- After a successful spin, user must complete a new qualifying order to spin again.
- Backend validates eligibility and selects the awarded wheel value before awarding points.

8. Multi-Currency Compatibility
Omnify Customer Rewards for WooCommerce provides a filter for currency conversion:
- Filter name: omnify_rewards_convert_amount
- Signature: apply_filters('omnify_rewards_convert_amount', null, $amount, $fromCurrency, $toCurrency)

If no converter is attached, Omnify Customer Rewards for WooCommerce falls back to the original amount.

9. Admin Screens
- WooCommerce > Settings > Omnify Customer Rewards: main settings
- WooCommerce > Adjust User Points: manually increase/decrease user points
- WooCommerce > Points History: audit trail view

10. Customer Experience
On My Account, customers can:
- View points balance and value
- Claim daily check-in points
- Open and play spin wheel (if eligible)
- Review points history

11. Security and Data Handling
- Nonce verification is used for AJAX and admin forms.
- Inputs are sanitized using WordPress sanitization functions.
- Dynamic output is escaped using WordPress escaping functions.

12. Key Data Keys
- User points: _omnify_rewards_user_points
- Point history: _omnify_rewards_point_history
- Last check-in date: _omnify_rewards_last_checkin_date
- Spin used flag per order: omnify_rewards_has_spun_for_order_{ORDER_ID}
- Product custom points meta: _omnify_rewards_custom_product_points

13. Release Package
Build a distribution zip:
- Command: npm run wporg:build
- Output: /dist/omnify-customer-rewards-woocommerce.zip

14. Support Notes
If a setting or spin action does not apply immediately:
- Ensure WooCommerce is active
- Ensure user is logged in for account actions
- Clear cache and retry
- Confirm nonce/session integrity and AJAX accessibility

End of document.
