How to use bulk CSV upload for the Spin the Wheel popup and game
Bulk CSV upload lets you add many Spin the Wheel prizes and coupon codes at once. Instead of creating each prize manually, you can upload one CSV file with your prize names, coupon codes, colors, winning chances, and win/loss settings.
Sample CSV
Use this format for your CSV file:
prize_name,unique_code,prize_bg_color (hex),prize_text_color (hex),weightage (number),is_win
10% OFF,WELCOME10-A1,#F14A16,#FFFFFF,8,true
10% OFF,WELCOME10-A2,#F14A16,#FFFFFF,8,true
10% OFF,WELCOME10-A3,#F14A16,#FFFFFF,8,true
FREE SHIPPING,FREESHIP-A1,#2563EB,#FFFFFF,4,true
FREE SHIPPING,FREESHIP-A2,#2563EB,#FFFFFF,4,true
FREE GIFT,GIFT-A1,#0B0B0B,#FFFFFF,2,true
TRY AGAIN,,#FFFFFF,#111827,5,false
BETTER LUCK NEXT TIME,,#F4F4F5,#111827,3,false
What each column means
prize_name
The name shown on the wheel slice, such as “10% OFF” or “TRY AGAIN”.
unique_code
The coupon code given to the visitor. This is required for winning prizes. Leave it empty for losing prizes.
prize_bg_color (hex)
The background color of the wheel slice.
prize_text_color (hex)
The text color of the wheel slice.
weightage (number)
The chance weight for that prize. A higher number means the prize is more likely to be selected.
is_win
Use true for winning prizes and false for losing prizes.
Step 1: Create or edit your Spin the Wheel widget
Open your Spin the Wheel popup or Spin the Wheel game in the editor.
or
Step 2: Save the widget first
Before uploading the CSV file, save the widget once.
This is important because the CSV prizes need to be connected to a saved widget. If the widget is not saved yet, the upload cannot safely store the prizes and coupon codes.
for popup -
for game -
Step 3: Switch from Manual mode to Bulk CSV mode
In the prize settings area, choose Bulk CSV mode.
In Manual mode, you can add prizes one by one. In Bulk CSV mode, you can upload a CSV file and let the system create the wheel slices for you.
for popup -
for game -
Step 4: Download or prepare the sample CSV
Use the sample CSV format shown in the editor.
You can download the sample CSV, update the prize names, coupon codes, colors, weightage, and win/loss values, then upload it.
Step 5: Upload the CSV file
Click the CSV upload option and select your completed CSV file.
After upload, the system reads the CSV and groups rows with the same prize_name into one visual wheel slice. For example, if you add 500 rows for “10% OFF”, the wheel still shows one “10% OFF” slice, but stores all 500 unique codes in the background.
Step 6: Check the auto-rendered wheel preview
After the upload is complete, the wheel preview updates automatically.
You should see the uploaded prize names, colors, and chances reflected in the preview. Winning prizes may show a placeholder code in the editor, but real visitors will receive actual unique coupon codes from your uploaded CSV.
for game -
for popup -
Step 7: Save the widget again
After confirming the uploaded prizes look correct, save the widget again.
for popup -
for game -
How winning and losing prizes work
Winning prizes should have:
- is_win set to true
- a valid unique_code
Losing prizes should have:
- is_win set to false
- an empty unique_code
Example losing row:
TRY AGAIN,,#FFFFFF,#111827,5,false
When a visitor lands on a losing slice, no coupon code is shown.
How unique coupon codes are handled
Each uploaded coupon code is stored safely and marked as unused.
When a visitor wins a prize, the system assigns one unused code for that prize and marks it as used. Once a code has been assigned, it will not be given to another visitor again.
If multiple visitors spin at the same time, the system still protects the coupon pool so the same code is not assigned twice.
What happens if a code is not available?
If the selected winning prize has no unused codes left, the visitor will not receive a fake or duplicate coupon.
Instead, the widget handles it safely and treats the result as unavailable, so the visitor is not shown the editor placeholder or an already-used code.
This protects your real coupon codes and avoids duplicate coupon distribution.
Brief implementation details
The Bulk CSV feature works in three main parts:
1. CSV upload in the editor
The editor sends the uploaded CSV file to the backend.
2. Backend storage
The backend reads the CSV, groups rows by prize_name, creates the visual wheel prizes, and stores each unique coupon code separately.
3. Live visitor spin
When a visitor spins the wheel, the widget asks the backend for one unused code for the selected prize. The backend marks that code as used before returning it, so the same coupon cannot be reused by another visitor.
The widget also waits for the real coupon code before showing the final result, so visitors do not see temporary editor placeholders.
Best practices
- Always save the widget before uploading a CSV.
- Use unique coupon codes for winning prizes.
- Leave unique_code empty for losing prizes.
- Use is_win=false for “Try again”, “Sorry”, or “Better luck next time” slices.
- Keep the CSV column names exactly as shown in the sample.
- Upload a fresh CSV if you want to replace or refresh the prize pool.