LoyaltyForge – Customer Club for WooCommerce

LoyaltyForge is an extensible WooCommerce customer-club plugin built around an immutable points ledger rather than a mutable balance-only model. It provides loyalty points, dynamic earning campaigns, membership tiers, reward coupons, referrals, expiration, refund/cancellation reversals, a responsive My Account experience, administration tools, REST endpoints, privacy integration and auditability.

Requirements

• WordPress 6.9+
• WooCommerce 10.8+
• PHP 7.4+
• MySQL/MariaDB with InnoDB and GET_LOCK() support required for economic operations. Native coupon posts and metadata must also use InnoDB.
• Single-site WordPress; multisite activation is rejected until site-scoped user metadata is implemented.

The plugin declares WooCommerce HPOS and Cart/Checkout Blocks compatibility. Order data is read through WooCommerce CRUD APIs; LoyaltyForge does not query legacy shop_order posts directly.

Implemented capabilities

Points and ledger

• Immutable custom-table transaction ledger
• Authoritative balances read directly from the ledger; obsolete user-meta caches can be cleared
• Signed credit/debit transactions
• Site/database-scoped MySQL advisory locks and one transaction across nested economic operations
• Idempotency keys to prevent duplicate event processing
• FIFO point buckets
• Configurable expiration period
• Expiration before balance use, plus batched daily maintenance
• Lifetime-earned and expiring-points calculations
• Manual admin adjustments with mandatory reason and audit record
• Negative balances allowed only for forced economic reversals such as refunds/cancellations

WooCommerce earning lifecycle

• Configurable eligible WooCommerce order statuses
• Configurable points per store-currency unit
• Configurable earning basis and rounding
• Tier earning multiplier
• Dynamic rules/campaign modifiers
• Cumulative partial-refund reconciliation, including cancellation and already-expired unused points
• Cancellation reversal
• One verified product-review bonus per customer/product
• Registration bonus
• Referral completion bonus
• Guest-checkout pending points with configurable claim window
• Guest claiming requires the order key and a matching account email. Automatic claiming is available only when a trusted integration supplies the loyaltyforge_customer_email_verified filter.
• Guest refund/cancellation reconciliation before or after claim
• Reward coupon usage linkage

Dynamic Rules & Campaigns

Administrators can create, edit and delete time-bounded order earning rules with:

• Priority
• Start/end dates
• Minimum/maximum order total
• Product/variation IDs
• Product category IDs
• User roles
• Membership tiers
• Payment method IDs
• Weekdays
• First-order condition
• Point multiplier
• Point-per-currency override
• Fixed bonus points
• Cumulative or highest-result conflict strategy

Membership tiers

Administrators can create/edit/delete tiers with:

• Lifetime-spend threshold
• Order-count threshold
• Lifetime-points threshold
• Earning multiplier
• Redemption multiplier
• Benefits metadata
• Sort order
• Active/disabled status

Tiers are recalculated after loyalty events and during scheduled maintenance.

Rewards and redemption

• Dynamic reward catalog
• Fixed-cart discount rewards
• Percentage rewards
• Free-shipping rewards
• Points cost
• Minimum order amount
• Tier restriction
• Stock
• Per-customer redemption limit
• Start/end dates
• Single-use WooCommerce coupon generation
• Coupon email restriction to the redeeming customer
• Configurable coupon expiration
• Direct points-to-coupon conversion using a configurable exchange rate, minimum, maximum and step
• Tier redemption-value multiplier
• Automatic point rollback if coupon issuance fails

Referral program

• Stable per-customer referral code
• Shareable referral URL
• Secure HTTP-only referral cookie
• Self-referral rejection
• Referrer/referred bonuses controlled by admin settings
• Bonuses issued only when the referred registered customer completes an eligible order
• Idempotent one-time completion
• Referral statistics in My Account

Customer experience

A responsive Customer Club WooCommerce My Account endpoint includes:

• Available balance
• Lifetime earned
• Points expiring within 30 days
• Referral count
• Tier and next-tier progress
• Reward catalog
• Direct points conversion
• Referral link and code
• Issued reward coupons
• Transaction history

Shortcodes:

• [loyaltyforge_dashboard]
• [loyaltyforge_points]
• [loyaltyforge_tier]

Administration

• Loyalty dashboard KPIs
• Tier distribution
• Health checks
• Customer balance/tier/order/spend table
• Manual adjustments
• Latest transaction ledger
• CSV transaction export
• Dynamic Rules & Campaigns UI
• Dynamic tiers UI
• Dynamic rewards UI
• Global settings
• Editable loyalty email templates
• Database health
• Clear obsolete balance caches
• Run maintenance immediately

Notifications

Configurable WooCommerce-styled email notifications for:

• Points earned
• Points deducted
• Tier changes
• Reward issuance
• Direct points conversion

Supported template tokens include {customer_name}, {site_name}, {points}, {points_name}, {balance}, {tier}, {coupon} and {value} where applicable.

REST API

Authenticated customer endpoints:

• GET /wp-json/loyaltyforge/v1/me
• GET /wp-json/loyaltyforge/v1/me/transactions
• GET /wp-json/loyaltyforge/v1/rewards
• POST /wp-json/loyaltyforge/v1/rewards/{id}/redeem
• POST /wp-json/loyaltyforge/v1/points/redeem

Privileged endpoint:

• POST /wp-json/loyaltyforge/v1/customers/{id}/adjust

Security and privacy

• Granular capabilities for settings, tiers, rewards, rules, reports, exports and point administration
• Nonces on state-changing admin/front-end forms
• REST permission callbacks
• Input sanitization and output escaping
• Prepared dynamic SQL values
• Server-authoritative balance/reward calculations
• Idempotent economic operations
• Per-customer concurrent mutation lock
• Immutable audit-friendly ledger
• WordPress privacy exporter/eraser integration
• Privacy-policy helper text
• Configurable uninstall retention

Background processing

LoyaltyForge uses WooCommerce Action Scheduler when available and falls back to WP-Cron. Scheduled maintenance expires due points, marks expired reward codes, and refreshes customer tiers in cursor-based batches. Continuation jobs avoid starving older customers. Transient order, registration and review failures enqueue retries.

Database tables

The plugin creates custom tables using the active WordPress prefix:

• *_loyaltyforge_transactions
• *_loyaltyforge_point_buckets
• *_loyaltyforge_tiers
• *_loyaltyforge_customer_tiers
• *_loyaltyforge_rewards
• *_loyaltyforge_redemptions
• *_loyaltyforge_rules
• *_loyaltyforge_referral_codes
• *_loyaltyforge_referrals
• *_loyaltyforge_guest_claims
• *_loyaltyforge_audit_log

Capabilities

• manage_loyaltyforge
• view_loyaltyforge_reports
• manage_loyaltyforge_points
• manage_loyaltyforge_tiers
• manage_loyaltyforge_rewards
• manage_loyaltyforge_rules
• manage_loyaltyforge_settings
• export_loyaltyforge_data

They are assigned to Administrator and Shop Manager on activation.

Extension hooks

Actions include:

• loyaltyforge_loaded
• loyaltyforge_transaction_posted
• loyaltyforge_tier_changed
• loyaltyforge_reward_redeemed
• loyaltyforge_points_converted
• loyaltyforge_referral_completed
• loyaltyforge_after_daily_maintenance

Filters include:

• loyaltyforge_order_points
• loyaltyforge_rule_matches_order

Behavior and integration notes

• Upgrade: version 1.1.0 adds a nullable, unique redemption request key and ensures plugin tables use InnoDB. Existing transactions are preserved. It does not reconstruct corruption that may already have occurred in earlier versions.
• Redemption: stock, point buckets, the debit, the native WooCommerce coupon, and the redemption record commit together. Retry REST redemption/adjustment requests with the same Idempotency-Key header. Customer forms supply a request key automatically. Without a supplied key, each service/API request is a new operation.
• Tiers: spend is the net value of paid orders after refunds in the store currency. Qualifying points exclude economic reversal debits; spending and expiry do not count as tier deductions. All configured thresholds must be met. Reward tier restrictions mean the exact selected tier.
• Campaigns: rate override → multiplier → fixed bonus. Cumulative mode adds only bonuses above the baseline; highest mode selects the largest result including the baseline. Neither mode reduces baseline earning. Weekday conditions use the store timezone. Product/category selections match any selected product or category; other condition groups must also match.
• Referrals: award both sides once for the first eligible order. Cancellation or full refund reverses both bonuses; a partial refund alone does not reverse the referral bonus.
• Guest claims: the account email must match the billing email, and the customer supplies the order key from the confirmation URL. Email verification integrations may return true from loyaltyforge_customer_email_verified only after verifying ownership. Login/registration alone is not verification.
• Currency: earning and tier spend use the store currency. Foreign-currency orders are skipped; no exchange-rate conversion is implemented.
• Shipping rewards: WooCommerce still needs a free-shipping method configured to accept a valid free-shipping coupon.
• Pause: disabling the program stops new automatic earnings, referral capture and redemptions. Refund reconciliation and expiry continue to keep existing balances correct.
• Privacy: exports paginate all plugin records. Erasure removes linked coupons and records while retaining a minimal account opt-out marker to prevent old events recreating erased rewards. WooCommerce/WordPress handle their own order/account records separately.
• Order status restoration: a cancelled/refunded order does not earn again on reactivation; its original award key remains consumed. A deliberate audited adjustment is needed if a merchant restores that benefit.

See REVIEW.md for the role-based audit and tests/README.md for reproducible validation.

Installation

1. Upload loyaltyforge-customer-club.zip in Plugins → Add Plugin → Upload Plugin.
2. Activate it with WooCommerce active.
3. Open Customer Club → Settings.
4. Review order statuses, point economics and retention settings.
5. Configure Membership Tiers, Rewards, and Rules & Campaigns.
6. Test earning, refund, redemption and expiration behavior on a staging store before production rollout.

Deliberately extension-ready rather than hard-coded

The core architecture leaves stable extension points for future modules such as POS/CRM adapters, SMS/push providers, advanced fraud scoring, RFM/cohort analytics, gamification, Elementor/Bricks widgets, multi-store networks, paid memberships, member pricing, product-access gates, omnichannel wallets and specialized accounting/liability reporting. These are not falsely advertised as complete integrations in version 1.1.0.

License

GPL-2.0-or-later.