Instant Win

Let customers find out if they won immediately after purchase — no waiting for the raffle to end.

Overview

Instant Win evaluates each ticket at purchase time. When a customer completes an order containing raffle tickets, the system checks each ticket against the configured win criteria. Results appear on the thank-you page and in the customer's My Account ticket list.

Instant Win works alongside the standard raffle draw. A raffle can have both instant winners (determined at purchase) and end-of-raffle winners (determined when the raffle closes).

Enabling Instant Win

Edit your raffle product.
Go to the Raffle Settings tab.
Find the Instant Win section.
Check Enable Instant Win.
Choose a Mode (see below).
Configure mode-specific settings.
Save the product.

Modes

Probability mode

Each ticket has an independent random chance of winning.

Setting	Description
Win probability (1 in N)	The denominator for the win chance. A value of 50 means each ticket has a 1-in-50 (2%) chance of winning.
Max instant winners	Maximum total instant winners for this raffle. Leave empty or 0 for unlimited. Once reached, no more instant wins are awarded.

Scroll to see all columns →

How it works: When a ticket is generated, the system calls random_int(1, N). If the result is 1, the ticket wins. Each evaluation is independent — buying 50 tickets does not guarantee a win.

Best for: Large raffles where you want occasional surprise winners without a predictable pattern.

Guaranteed mode

Exactly one winner every N tickets, with the winning position randomized within each interval.

Setting	Description
Win every N tickets	The interval size. A value of 25 means one winner in every 25 tickets sold.
Max instant winners	Maximum total instant winners. Leave empty or 0 for unlimited.

Scroll to see all columns →

How it works: Tickets are grouped into windows of N. For each window, a random winning position (1 to N) is generated just-in-time when the first ticket in that window is processed. The customer who receives the ticket at that position wins.

Best for: Competition sites where you want a guaranteed win rate (e.g., "1 in every 25 tickets wins!") while keeping the exact winning position unpredictable.

Product page display

When Instant Win is enabled on an active raffle, an "Instant Win!" badge appears on the product page with the message: "Find out if you won immediately after purchase."

The badge uses a gold gradient design and is visible only while the raffle is active.

Require instant payment

When Instant Win is enabled, a "Require instant payment" checkbox appears (checked by default). When active, offline payment gateways (bank transfer, cheque, cash on delivery) are automatically hidden at checkout for this raffle product. This ensures tickets are evaluated immediately after payment, not after manual order processing.

This works in combination with the per-product checkout settings where you can disable specific gateways per raffle.

Thank-you page results

After a successful order, the WooCommerce thank-you page shows instant win results for each ticket:

Winners see a congratulations message with confetti-style styling.
Non-winners see a "Not a winner this time" message with encouragement.

Each result displays the ticket number and outcome.

My Account display

In My Account → My Tickets, tickets with instant win results show a tag next to their status:

Instant Win! (gold tag) — the ticket won.
No instant win (grey tag) — the ticket did not win.

Winner processing

When a ticket wins an instant prize:

The ticket status is updated (default: 'winner'; Pro can keep it as 'active' for hybrid eligibility — see Two chances to win).
A winner record is created with selection_method = 'instant_win'.
The standard winner notification email is sent to the ticket holder.
If the raffle has auto-fulfill enabled, the prize is fulfilled (order or credit coupon created).
The evaluation is logged to the audit trail.

Instant winners appear in the WooCommerce → Raffle Tickets → Winners tab alongside raffle-end winners, with "Instant Win" shown as the selection method.

Max winners cap

The Max instant winners setting prevents more instant wins than intended. Once the cap is reached:

No further instant win evaluations occur for new tickets.
New tickets are still valid for the end-of-raffle draw.
The cap is checked before each evaluation.

Leave the field empty or set to 0 for unlimited instant winners.

Audit logging

Every instant win evaluation is logged to the rfwc_log table with:

Ticket ID and number
Raffle product ID
Mode (probability or guaranteed)
Result (won or lost)
Timestamp

Access logs via the Analytics page activity log or directly in the database.

Configuration examples

Competition site (guaranteed wins)

Mode: Guaranteed
Win every N tickets: 25
Max instant winners: 10
Require instant payment: Yes

One winner in every 25 tickets. Maximum 10 instant winners total. Offline gateways hidden.

Charity raffle (low probability bonus)

Mode: Probability
Win probability: 1 in 100
Max instant winners: 3
Require instant payment: No

Each ticket has a 1% chance. Maximum 3 instant winners. All payment methods allowed.

Promotional giveaway (frequent wins)

Mode: Probability
Win probability: 1 in 10
Max instant winners: (empty)
Require instant payment: Yes

10% chance per ticket. No cap on winners. Online payment required.

Interaction with other features

Payment gateway restrictions

Instant Win's "Require instant payment" works alongside the per-product gateway restriction field. Both are applied — if you manually disable Stripe AND have instant payment required, customers will only see gateways that are neither manually disabled nor offline.

Unique winner enforcement

The unique winner setting (Task #32) applies to the end-of-raffle draw, not to instant win evaluations. A customer can win an instant prize and still be eligible for the main draw.

Gift tickets

Gift tickets are evaluated for instant win just like self-purchased tickets. If a gift ticket wins, the recipient (not the purchaser) is recorded as the winner.

Bulk pricing

Bulk ticket discounts apply normally. More tickets at a discount means more chances at an instant win.

Hooks for developers

Filters

Hook	Parameters	Description
`rfwc_instant_win_evaluate`	`$result` (null), `$ticket`, `$product`, `$mode`	Override or extend win/lose evaluation. Return `null` to use core logic, `true` to force a win, `false` to force a loss. This is the main extension point used by the Pro addon.
`rfwc_instant_win_prize_tier`	`$prize_tier` (int), `$ticket`, `$product`	Filter the prize tier for an instant winner. Core always returns `1`. Pro addon uses this to assign multiple tiers.
`rfwc_instant_win_ticket_status`	`$status` (`'winner'`), `$ticket`, `$product`	Filter the ticket status after an instant win. Return `'active'` to keep the ticket eligible for the main draw (hybrid "two chances to win" mode). Default: `'winner'`.
`rfwc_should_fulfill_prize`	`$should_fulfill` (`true`), `$ticket`, `$raffle`	Whether core should proceed with prize fulfillment. Return `false` to skip core fulfillment (e.g. when Pro handles IW prizes with a separate config). Default: `true`.

Scroll to see all columns →

Actions

Hook	Parameters	Description
`rfwc_instant_win_evaluated`	`$ticket`, `$is_winner`, `$mode`, `$product`	Fires after every instant win evaluation completes (win or lose).
`rfwc_instant_winner_created`	`$winner`, `$ticket`, `$product`, `$order`	Fires after an instant winner record is saved to the database.
`rfwc_winner_selected`	`$ticket`, `$raffle_id`	Triggers the standard winner notification email for instant winners (same hook used by the end-of-raffle draw).
`rfwc_iw_prize_order_created`	`$order`, `$ticket`, `$raffle`, `$winner`	Fires after a Pro IW-specific prize order is created (separate from the core `rfwc_prize_order_created` hook).
`rfwc_iw_prize_coupon_created`	`$coupon`, `$ticket`, `$raffle`, `$winner`	Fires after a Pro IW-specific credit coupon is created.

Scroll to see all columns →

Pro addon: Advanced Instant Win

Raffle for WooCommerce Pro extends the core instant win system with additional capabilities. These features are non-destructive — they add functionality without changing or limiting the free plugin's behavior.

Pre-selected winning tickets

Admin can designate specific ticket numbers as guaranteed instant winners. When a customer purchases a ticket whose number matches a pre-selected entry, it automatically wins regardless of the probability/guaranteed mode settings. Non-matching tickets still go through the normal evaluation.

Manual entry: type ticket numbers (matching your format, e.g. 0001, 0015, 0042)
CSV import: bulk import via ticket_number,prize_tier format
Zero-padding normalization: 0042 and 42 are treated as the same ticket

Multiple prize tiers (cosmetic)

Configure up to 5 instant win prize tier labels (e.g., "1st Prize", "Runner Up") with descriptions. These display as styled cards on the product page with medal icons. Each pre-selected ticket can be assigned to a specific tier via CSV import.

Separate IW prize configuration

By default, instant win prizes and the main raffle draw share the same prize config. Pro adds a separate IW prize section in the Raffle Settings panel with its own:

Field	Description
IW prize type	Product from store, Store credit / Coupon, or Custom — independent of the main draw prize type
IW prize products	WooCommerce product search per tier (1-5)
IW credit amounts	Credit/coupon amounts per tier
IW descriptions & values	Custom prize descriptions and display values per tier
Auto-fulfill IW prize	Automatically create a free prize order or credit coupon for instant winners

Scroll to see all columns →

When configured, instant win prizes fulfill from this IW config while main draw prizes use the core config. If no separate IW config is set, both use the core config (backward-compatible).

Example setup:

Main draw prize: PlayStation 5 (Product from store)
IW prize: £10 Amazon Voucher (Store credit, £10 per tier)
Result: Instant winners get the voucher; end-date draw winner gets the PS5

Two chances to win (Pro)

When a raffle runs in hybrid mode (instant win + end-date draw both active), Pro adds a per-product toggle:

"Two chances to win" — When enabled, instant win tickets keep 'active' status instead of 'winner'. This means:

The ticket is counted as an instant winner (winner record created, prize fulfilled).
The ticket remains in the main draw pool and can potentially win the end-date prize too.
Matches the UK competition industry standard of "two chances to win in one".

When disabled (default), instant win tickets are excluded from the main draw — the current free plugin behavior.

This toggle only appears in hybrid mode. In IW-only mode (no main draw), there is no pool to stay in.

Frontend: two-section prize display

When separate IW prizes are configured, the product page shows two distinct sections:

Instant Win Prizes — with lightning bolt icon, showing real prize data (product names, credit amounts, or custom descriptions) per tier.
Main Draw Prize — with trophy icon, heading above the core prize display.

In IW-only mode, only the Instant Win section shows.

How it integrates

The Pro addon hooks into core filters:

Filter	What Pro does
`rfwc_instant_win_evaluate`	Checks if the ticket number is pre-selected; returns `true` if matched
`rfwc_instant_win_prize_tier`	Returns the assigned tier for pre-selected tickets
`rfwc_instant_win_ticket_status`	Returns `'active'` when "Two chances to win" is enabled in hybrid mode
`rfwc_should_fulfill_prize`	Returns `false` for IW winners that have separate IW prize config (Pro handles fulfillment itself)

Scroll to see all columns →

No core code is modified. If the Pro addon is deactivated, instant win reverts to standard behavior seamlessly.

Troubleshooting

Instant win not evaluating

Ensure "Enable Instant Win" is checked on the product.
Check that the Generate Tickets On setting matches your order flow — tickets must be generated before evaluation occurs.
Check that the max winners cap has not been reached.
Review the activity log for errors.

Offline gateways still showing

Ensure "Require instant payment" is checked on the product.
Clear any caching plugins.
Check that no other plugin is overriding the woocommerce_available_payment_gateways filter at a later priority.

Results not showing on thank-you page

Ensure the order contains raffle tickets with instant win enabled.
Check that tickets were generated (order must reach the configured trigger status).
Review browser console for JavaScript errors from other plugins.

Winner Selection

PDF Tickets & QR