Skip to main content

Raffles

Admin

Raffles let customers purchase entries at the register for a chance to win a prize. Each raffle automatically creates a sellable product in your catalog — cashiers ring it up like any other item and entries accumulate until the scheduled draw. Winners are selected randomly and can be drawn manually or on an automatic schedule.

Enabling Raffles​

The Raffles feature requires a feature flag to be active:

  1. Navigate to Settings > Edit Settings.
  2. Scroll to the Promo & Loyalty section.
  3. Enable Enable Raffles.
  4. Save settings.

Once enabled, the Raffles link appears in the admin navigation and entry products become visible in the POS catalog.

info

The feature flag can also be enabled at the platform level for a store by a super-admin under Platform > Stores.

How Raffles Work​

  1. An admin creates a raffle with a name, prize description, entry price, and draw schedule.
  2. The system automatically creates a product (e.g., "Weekly Ounce Draw Entry") in a Raffles category with a fixed SKU (RAFFLE-{id}).
  3. Cashiers add this product to a sale at the register. Each unit quantity sold creates one entry for the attached customer.
  4. Entries accumulate until the draw date arrives.
  5. A winner is selected randomly from all active entries — either manually by an admin or automatically by a background job that runs every 15 minutes.
  6. After the draw, recurring raffles (weekly, biweekly, monthly) can be reset to start a new round. One-time raffles remain in a drawn state.
Customer required

Entries are only created when a customer is attached to the sale. If a sale has no customer, the raffle entry product is sold normally but no entry is recorded.

Creating a Raffle​

Navigate to Raffles in the admin panel and click New Raffle.

Basic Settings​

FieldRequiredDescription
NameYesIdentifies the raffle. Also used as the POS product name (e.g., "Weekly Ounce Draw").
PrizeYesShort description of the prize shown in the raffle list and on the detail page.
DescriptionNoOptional longer description for internal reference.

Pricing & Limits​

FieldRequiredDescription
Entry PriceYesCost per entry, charged at the POS. Must be greater than $0.
Max Entries Per CustomerNoCap on how many entries a single customer can hold. Leave blank for unlimited.

Draw Settings​

FieldRequiredDescription
Draw FrequencyYesWeekly, Biweekly, Monthly, or One Time.
Draw DayConditionalDay of the week the draw occurs. Required for weekly and biweekly raffles.
Next Draw DateNoSpecific datetime for the next draw. Auto-calculated from frequency and day if left blank.

For monthly raffles the draw is scheduled for the first day of the next calendar month (offset by the draw day setting). For one-time raffles the next draw date is used as-is; it is not recalculated after a draw.

Active Toggle​

Check Active to make the raffle live. When active, the POS entry product is visible in the catalog and new entries can be created. Deactivating a raffle hides the entry product at POS but does not delete existing entries.

Click Create Raffle to save.

The POS Entry Product​

When a raffle is created or its price/name/active state changes, the system automatically syncs a linked product:

  • Name: {Raffle Name} Entry
  • SKU: RAFFLE-{id} (unique, used for barcode scanning)
  • Category: Raffles (created automatically if it does not exist)
  • Stock: Set to 999,999 — treated as unlimited
  • Price: Matches the raffle entry price
  • Active: Mirrors the raffle's active state

If you need to adjust the product description or other catalog fields, use the Edit Product link on the raffle detail page.

Managing Entries​

The raffle detail page shows a paginated table of all entries. Each row includes:

  • Entry number (sequential, assigned atomically to prevent duplicates)
  • Customer name and phone (denormalized from the customer record at time of purchase)
  • Purchase date and time
  • Status: Active (in the draw pool) or Winner (already drawn)

Entries are created automatically when a qualifying sale completes. They cannot be manually added or removed through the admin UI.

Running a Draw​

Manual Draw​

  1. Open the raffle detail page.
  2. The Draw section appears when the raffle is active and has at least one active entry.
  3. Click Draw Winner.
  4. A fullscreen slot-machine animation runs, cycling through all entries before landing on the winner.
  5. The winner's name and entry number are revealed and the raffle moves to drawn status.

The animation fetches all current active entries via JSON and cycles them randomly before revealing the pre-selected winner. The actual winner selection happens server-side before the animation begins.

Automatic Draw​

The system runs a background job (RaffleAutoDrawJob) on a 15-minute cron schedule. The job finds all active raffles whose next_draw_at is in the past and have at least one active entry, performs the draw, and — for recurring raffles — immediately resets for the next round.

If a scheduled draw time passes while no entries exist, the job skips that raffle without drawing.

Resetting for the Next Round​

After a draw completes on a recurring raffle, an admin must manually confirm the reset:

  1. The winner banner appears on the raffle detail page.
  2. Click Reset & Start New Round.
  3. Confirm the prompt.

The reset action:

  • Clears the winner fields
  • Deletes all entries for the completed round
  • Resets the entry count to zero
  • Recalculates the next draw date based on frequency and day

One-time raffles do not show the reset button. They remain in drawn status permanently.

caution

Resetting is irreversible. All entries from the completed round are permanently deleted.

Raffle Statuses​

StatusMeaning
activeAccepting entries; eligible for draw.
drawingDraw is in progress (brief transitional state).
drawnWinner has been selected. Awaiting reset (recurring) or closed (one-time).
cancelledRaffle was cancelled. No further draws.

Best Practices​

  1. Attach customers at the register. Entries are only created when a customer is on the sale. Train cashiers to look up or create a customer record before ringing up a raffle entry.
  2. Set an entry cap when appropriate. Max Entries Per Customer prevents one customer from dominating the pool without limiting overall participation.
  3. Use one-time raffles for special events. One-time draws are useful for grand prize giveaways where you do not want automatic recurrence.
  4. Let the auto-draw run for recurring raffles. Scheduling draws at 6 PM on the configured day means the 15-minute job will catch them within 15 minutes of the cutoff without any manual action.
  5. Review entries before drawing manually. The entry count and list are visible on the detail page — confirm the pool looks correct before clicking Draw Winner.
  6. Do not delete a raffle with entries unless intended. Deletion removes the raffle, all its entries, and the linked POS product. The action prompts for confirmation but cannot be undone.

What's Next?​

  • Promo Games -- Spin-to-win and scratch card promotions triggered by sales.
  • Sale Campaigns -- Date-range and BOGO discount campaigns.
  • Feature Flags -- Enable or disable raffles and other optional features.