Lucky Wheel / Spin to Win

Interactive HTML5 canvas prize wheel with server-side outcome determination. Works in two modes: product-tied (quick setup on any raffle product) and standalone (dedicated admin page, usable anywhere in your store — cart, checkout, thank-you, popup, or shortcode).

---

Two Ways to Create a Wheel

Product Wheel (Quick Setup)

Best for raffle owners who want a wheel on their product page with minimal configuration.

• Edit a raffle product.
• In the PRO Features section, check Lucky Wheel.
• Choose Quick setup (configure slices inline) or Use existing wheel (link a standalone wheel).

Standalone Wheel

Best for store-wide marketing: cart abandonment recovery, checkout incentives, lead generation, or post-purchase re-engagement.

• Go to WooCommerce → Lucky Wheels → Add New.
• Give it a title (e.g. "Summer Sale Spinner").
• Configure slices, display rules, coupon settings, and spin limits.
• Publish.

---

Configuring Slices

Each slice of the wheel represents one possible outcome. A wheel needs at least 2 slices.

Free Ticket (standalone wheels)

When using a standalone wheel, the Free Ticket prize type shows an additional Target Product dropdown. This lets you select which product the 100% discount coupon applies to. If left empty, the coupon has no product restriction.

Default slices

When enabling a wheel for the first time, these defaults are pre-populated:

---

Display Rules (Standalone Wheels)

Configure where standalone wheels appear automatically, without shortcodes.

Product pages

When shown on product pages, the wheel renders before the add-to-cart form by default.

WooCommerce pages

Block & Classic compatibility

All placements detect whether WooCommerce is using the block-based cart/checkout (default since WooCommerce 8.3) or the legacy shortcode pages and hook in correctly for both.

---

Popup / Modal Mode

Show the wheel as a popup triggered by user behavior.

Settings

How it works

• The popup renders as a native HTML <dialog> element in the page footer.
• The selected trigger fires on the appropriate event.
• The dialog opens with a backdrop overlay and entrance animation.
• The close button (×) or clicking outside dismisses it.
• After closing, the cooldown prevents it from showing again for the configured number of days.

---

Coupon Settings

All auto-generated coupons share these characteristics:

• Single-use (1 redemption)
• Configurable expiry (default: 7 days, overridable per wheel or via global settings)
• Optional minimum order amount
• Described as "Lucky Wheel prize — [wheel name]"

Coupon scope (standalone wheels)

For product-tied wheels, coupons are automatically scoped to that raffle product.

Auto-cleanup

Expired wheel-generated coupons are automatically trashed by a daily WP-Cron job. This can be toggled on/off in the global Pro settings.

---

Email Gate & Lead Generation

Require visitors to enter their email address before they can spin. Turns the wheel into a lead generation tool.

Enabling

• Edit a standalone wheel.
• In the Spin Limits meta box, check Require email before spinning.
• Optionally enable the consent checkbox and customize the consent text (e.g. "I agree to receive marketing emails").

How it works

• The wheel renders with an email form overlay instead of the Spin button.
• The visitor enters their email (and ticks consent if required).
• The email is validated and checked for duplicates (same email cannot spin the same wheel twice).
• On success, the overlay disappears and the Spin button becomes active.
• If the visitor wins a coupon, the coupon code is emailed to them using WooCommerce's branded email templates.

GDPR consent

When enabled, a checkbox with custom text appears below the email input. The form cannot be submitted without ticking it. Consent status is recorded in the database.

Integration hooks

After an email is collected, the action rfwc_pro_wheel_email_collected fires with four parameters:

do_action( 'rfwc_pro_wheel_email_collected', $email, $wheel_id, $row_id, $consent );

Use this to integrate with Mailchimp, Mailpoet, ConvertKit, or any other email service.

Admin: Collected Emails

Go to WooCommerce → Lucky Wheels → Collected Emails to view all collected emails.

CSV columns: Email, Wheel, Coupon Code, Consent (Yes/No), IP, Date.

---

Thank-You Page / Post-Purchase

Show the wheel on the order confirmation page as a re-engagement tool: "You just ordered — spin for a reward on your next purchase!"

Order-aware features

---

Sound Effects

When enabled, the wheel plays sounds using the Web Audio API (no external files):

Sound can be toggled per wheel or set as a global default.

---

Spin Tracking

The server enforces the max spins limit — even if the frontend button is visible, exceeding the limit returns an error.

---

Shortcode

[raffle_wheel id="123"]

The shortcode handler automatically detects whether the ID belongs to a product or a standalone wheel and renders accordingly.

---

Global Pro Settings

Go to WooCommerce → Settings → Raffle → Pro to configure store-wide defaults.

Per-wheel settings always override global defaults. Empty/unset per-wheel values fall back to the global value.

---

How Spinning Works (Technical)

• Customer clicks Spin! (or submits email first if email gate is active).
• An AJAX request is sent to the server with the wheel/product ID (and order ID if on thank-you page).
• The server validates: wheel exists, user hasn't exceeded max spins, email gate passed, order not already spun.
• A winning slice is picked using weighted random selection (random_int — cryptographically secure).
• If the prize requires a coupon, a WooCommerce coupon is created with the configured settings.
• The server returns the winning slice index and a rotation angle.
• The frontend animates the wheel (4.5 second easing animation) to land on the winning slice.
• A result card appears showing the outcome — with a copy-to-clipboard button for coupon codes.

Security: The outcome is always determined server-side. The frontend animation is purely visual — the wheel always lands on the server-determined slice.

---

Prize Types

---

CSS Classes

Wheel

Email Gate

Popup

---

Files Reference

---

Action & Filter Hooks