WooRewards

Overview

WooRewards turns your WooCommerce store into a loyalty program. Customers earn points when orders are completed, spend them at checkout or in a reward catalog, and can progress through tiers, complete product quests, and invite friends via referrals.

Admin tools include a searchable customer points table (bundled DataTables, no CDN), bulk balance updates, and dedicated screens for levels, quests, and referrals.

Feature checklist (v1.4.1)

Requirements

WooCommerce High-Performance Order Storage (HPOS) is supported. The plugin declares compatibility with custom order tables.

Installation

1. Install and activate WooCommerce.
2. Upload the woo-rewards folder to wp-content/plugins/ or install the ZIP from your purchase.
3. Activate WooRewards — Advanced Reward Points System under Plugins.
4. Go to WooRewards → Settings and set the earning rate (default is 10%).
5. Visit Settings → Permalinks and click Save Changes once if the My Account “My Points” page returns 404 (rewrite rules are flushed on activation).
6. Optional: enable Pay with Points under WooCommerce → Settings → Payments if you want full balance checkout.

Store owner guide

What you need to configure and maintain after installation.

Who can access admin?

Users with manage_woocommerce (shop managers) or manage_options (administrators). Change the required capability with the woo_rewards_admin_capability filter.

Customer guide

What shoppers must do to earn, track, and spend points.

Quick start

Recommended first steps

• Set earning rate under WooRewards → Settings (e.g. 10% of subtotal → points).
• Review customers under WooRewards → Points Management.
• Configure tiers and quests under Levels & Quests if you use gamification.
• Adjust referral bonuses under WooRewards → Referrals.
• Add rewards under WooRewards → Reward catalog for coupon redemptions.

How points are valued

By default, points are stored and displayed using the store currency format (1 point ≈ 1 currency unit for earning and redemption math). Example: at 10%, a $100 order subtotal awards $10 worth of points.

Earning points

When points are awarded

Points are added when an order moves to Completed. Only logged-in customers with a registered account receive points (guest checkout earns nothing). The calculation uses the order subtotal multiplied by your configured percentage.

Each order is credited only once: order meta _woo_rewards_points_awarded prevents duplicate grants if status changes to Completed again.

Settings

WooRewards → Settings → Earning rate — percentage from 0 to 100 (step 0.1). Saved via a secure admin action so shop managers with manage_woocommerce can update it without needing manage_options.

Notifications & history

• Email when points are earned or used at checkout (if WordPress mail succeeds).
• Each transaction is appended to the user's points history (shown on My Points).
• Lifetime points increment for tier badges (tiers do not change the earning % by themselves).

Quest bonuses

If product quests are configured, completing an order that includes a quest product can award extra bonus points (see Levels & quests).

Spending points

Checkout checkbox (partial or combined payment)

On checkout, logged-in customers with a balance can opt in to use points. A negative cart fee labeled Points Usage reduces the total. The discount is capped at the lesser of the customer's balance and the cart total (subtotal + shipping before the fee). If points do not cover the full amount, the customer pays the remainder with another payment method.

Points are deducted when the order is created (not on completion). An order note records the amount used.

Pay with Points gateway

A WooCommerce payment method Pay with Points appears only when the customer's balance is greater than or equal to the full cart total. The order is marked paid and the full total is deducted from the balance.

If an order paid entirely with this gateway is cancelled or refunded, points are restored to the customer balance.

Reward catalog

Customers can spend points on catalog items that generate single-use WooCommerce coupons (see Reward catalog).

Storefront display

WooRewards shows earning hints and balances in standard WooCommerce locations:

• Single product — estimated points for the product.
• Shop / category loops — points hint after the product title area.
• Cart — balance, earning estimate, and (for logged-in users) context before totals.
• Checkout — balance, optional “use points” control, and AJAX-friendly session handling.

My Account

WooRewards adds two WooCommerce account menu items (save permalinks after install if links 404):

Admin screens

All WooRewards menus appear under the top-level WooRewards item (dashicons-awards). Access uses manage_woocommerce by default; site administrators with manage_options are also allowed.

Points Management details

• Table: search/sort all listed customers; edit one user's balance inline and save per row.
• Bulk form: pick multiple users (Ctrl+click), choose add / subtract / set, enter amount, apply to selected only (not “all users” in one click).
• Directory loads up to 1,000 most recently registered customers by default (filter: woo_rewards_points_management_user_limit).
• DataTables assets are bundled under assets/vendor/datatables/ (MIT, see NOTICE.txt).

Levels & quests

Loyalty tiers

Tiers are based on lifetime points earned (cumulative from completed orders and bonuses, not current spendable balance). Default tiers: Bronze (0), Gold (500), VIP (2000) — all editable (slug, label, minimum threshold, color).

Product quests

Under Levels & Quests, define quests by WooCommerce product ID: bonus points, optional label, and “repeatable” flag. When a completed order line includes that product, extra bonus points are granted (on top of the global %). Non-repeatable quests are tracked per customer so they only pay once.

Referrals

Each logged-in customer gets a unique code (stored in user meta). Their shareable URL looks like https://yoursite.com/?ref=CODE and is shown on My Points.

Attribution flow

1. Visitor opens ?ref=CODE; if the code is valid, a first-party cookie woo_rewards_ref is set for 30 days (HttpOnly).
2. When the visitor registers (WordPress or WooCommerce customer), they are linked to the referrer (woo_rewards_referred_by). Self-referral and invalid codes are ignored.
3. When that new customer completes their only completed order (first ever), both sides receive configurable bonus points (defaults: inviter 100, invitee 50). Normal order % points still apply separately.

Admin: WooRewards → Referrals

• Enable or disable the whole program.
• Set inviter and new-customer bonus amounts (0 disables that side).

Important limits

• No bonus for link clicks alone — registration + first completed order required.
• Guest checkout without an account does not attach a referrer.
• Referral bonus runs once per invited customer (woo_rewards_ref_reward_done).
• Not a multi-level or recurring commission on every future order.

Reward catalog

Store owner: create rewards

Go to WooRewards → Reward catalog → Add new. Each woo_reward_item supports title, description, featured image, and redemption settings:

• Points cost — balance deducted on redeem
• Reward type — cart % discount, fixed cart discount, or 100% off one product
• Discount amount — percent (0–100) or fixed store currency amount
• Product ID — required for free-product rewards

Publish the item so it appears in the customer Reward shop.

Customer: redeem

1. Open My Account → Reward shop.
2. Choose a reward with enough balance and submit redeem.
3. Points are deducted; a single-use WooCommerce coupon code is shown in a success message.

If coupon creation fails, points are refunded automatically when possible.

What is not included

WooRewards focuses on loyalty, gamification, and referrals. The following are not built in (use filters or another extension if needed):

• Different earning % per product, category, or tag (only global % + per-product quest bonuses).
• Automatic points for guest orders or subscribers without WooCommerce customer accounts.
• “Give X points to every customer” in one admin click without selecting users in bulk form.
• CSV import/export of balances.
• Tier levels that automatically change the earning percentage (tiers are status badges based on lifetime points).
• Multi-level marketing or lifetime commission on all referred orders.

Privacy & data

WooRewards stores loyalty data in user meta, including balance, history JSON, lifetime points, referral fields, and quest progress. Referrals may set the woo_rewards_ref cookie as described above.

• Suggested privacy policy text is registered for WordPress Settings → Privacy.
• Personal data export and erase hooks integrate with WordPress privacy tools.

Deleting the plugin via WordPress runs uninstall.php, which removes plugin options, relevant user meta, and reward catalog posts.

Developers

Filters

// Earning percentage (option default still applies if not filtered)
add_filter( 'woo_rewards_points_percentage', function ( $pct ) {
    return 15;
} );

// Points calculated from subtotal
add_filter( 'woo_rewards_calculate_points', function ( $points, $order ) {
    return $points;
}, 10, 2 );

// Max discount when using points at checkout
add_filter( 'woo_rewards_order_discount', function ( $discount, $order_count ) {
    return $discount;
}, 10, 2 );

// Admin menu capability (default: manage_woocommerce)
add_filter( 'woo_rewards_admin_capability', function ( $cap ) {
    return 'manage_woocommerce';
} );

// Points Management user list size (default 1000)
add_filter( 'woo_rewards_points_management_user_limit', function ( $limit ) {
    return 2000;
} );

Actions

// After base order points are saved
do_action( 'woo_rewards_order_completed_points', $order_id, $user_id, $earned );

Constants & meta

• WOO_REWARDS_USER_META_POINTS — woo_rewards_points (legacy reward_points migrated on read)
• WOO_REWARDS_ORDER_META_POINTS_AWARDED — _woo_rewards_points_awarded on orders
• Options: woo_rewards_percentage, woo_rewards_level_tiers, woo_rewards_quest_rules, woo_rewards_ref_*, etc.

Multilingual

Translation-ready (woo-rewards text domain). Included: languages/woo-rewards.pot, Turkish woo-rewards-tr_TR.po / .mo. Helpers in includes/multilingual.php support common WPML/Polylang setups.

FAQ

Why didn't my test order award points?

Points apply only when the order status is Completed and the order has a registered customer and a positive subtotal.

Why is “Pay with Points” hidden?

The gateway appears only when the logged-in customer's balance covers the entire cart total after other adjustments. Otherwise use the checkout “use points” checkbox.

My Points page shows 404

Re-save permalinks. The plugin flushes rewrite rules on activation and version updates.

Who can manage WooRewards?

Users with manage_woocommerce or manage_options (woo_rewards_current_user_can_manage()).

Why did a customer get points twice on the same order?

From v1.4.1 onward, base order points should only apply once per order. Update to the latest version if you see duplicates from older builds.

Referral did not work — why?

Common causes: referrals disabled in admin, invitee did not register after clicking the link, cookie expired (30 days), invitee already had a completed order before the referral bonus ran, or self-referral.

Why is a customer missing from Points Management?

The list shows up to 1,000 recently registered users with roles customer, subscriber, or administrator. Increase the limit with woo_rewards_points_management_user_limit or adjust the user's role.

Uninstall

To remove all plugin data, delete WooRewards from the Plugins screen (do not only deactivate). The uninstall routine deletes options, user meta (points, history, gamification, referrals), woo_reward_item posts, and order meta _woo_rewards_points_awarded (postmeta and HPOS tables when present).