Surprise Boxes
Surprise Boxes are mystery reward containers that add an element of excitement and gamification to your loyalty program. When a customer opens one, they receive a randomly selected reward based on the probabilities you configure. The anticipation of "what will I get?" makes Surprise Boxes one of the most engaging loyalty features.
This page is the complete reference for every Surprise Box setting, rule, and edge case. If you are creating your first Surprise Box, start with the Create Your First Surprise Box guide and come back here when you need details.
What is a Surprise Box?
A Surprise Box is a mystery reward with multiple possible outcomes. You define a set of possible rewards (points or vouchers), assign each one a probability, and when a customer opens the box, the system randomly selects one reward based on those probabilities.
Example: A "Lucky Coffee Box" priced at 50 points might contain:
| Reward | Probability |
|---|---|
| 10 bonus points | 50% |
| Free Coffee voucher | 30% |
| 50 bonus points | 15% |
| Free Meal voucher | 5% |
Half the time, the customer gets 10 points. But there is a 5% chance of winning a free meal. That possibility is what makes the box exciting.
Surprise Boxes can be:
- Purchasable: Customers buy them in the points shop using loyalty points.
- Reward-only: Cannot be purchased -- only given as rewards from challenges or Battle Pass tiers.
Surprise Box Fields Reference
This section documents every field you encounter when creating or editing a Surprise Box.
Name
| What it is | The title customers see in the points shop and when opening the box |
| Valid values | Any text (required) |
| Default | None |
The name sets the tone for the entire experience. An exciting name makes the box feel like a treat, not a transaction.
Tips for naming:
- Use evocative language: "Golden Mystery Box", "Chef's Surprise", "Lucky Draw". Make it sound special.
- Match the theme to the contents: If the box contains drink vouchers, "Drink Roulette" works better than "Mystery Box #3".
- Avoid generic names: Every restaurant has a "Mystery Box". Differentiate yours.
- Keep it short: 2-4 words. The name appears on a compact card in the points shop.
Description
| What it is | A short description shown in the customer app |
| Valid values | Any text (optional) |
| Default | Empty |
Use the description to hint at what is inside without giving everything away. For example: "Could be a free coffee... or could be a free meal. Only one way to find out."
Price (Points)
| What it is | The number of loyalty points a customer must spend to purchase the box |
| Valid values | Any positive integer, or empty for reward-only |
| Default | Empty (reward-only) |
Purchasable boxes (price > 0): Appear in the customer's points shop. Customers spend points to buy and open them.
Reward-only boxes (price empty): Do not appear in the shop. Can only be given through challenges, battle pass tiers, or other reward mechanisms. This makes them feel exclusive.
Pricing strategy:
- Price the box below the average expected reward value so it feels like a good deal. If the average outcome is worth ~80 points of value, price the box at 50-60 points.
- Compare the box price to your individual voucher prices. A box should feel like a better deal than buying a voucher directly (because of the randomness risk).
- Offer boxes at different price points: a cheap "Starter Box" (20-30 points) with modest rewards and a premium "Deluxe Box" (80-100 points) with better rewards.
Reward-only boxes are especially powerful as Battle Pass tier rewards. A customer who earns a mystery box through progression feels like they are getting something exclusive that cannot be bought.
Max Usage
| What it is | The total number of times the box can be claimed across all customers |
| Valid values | Any positive integer, minimum 1 (required) |
| Default | None |
Once the max usage is reached, the box becomes unavailable. No more customers can purchase or receive it.
How to set it:
- High usage (500-1000+): Effectively unlimited for most restaurants. The box stays available until you deactivate it.
- Medium usage (50-200): Creates moderate scarcity. Good for monthly boxes that you refresh regularly.
- Low usage (10-50): Creates high scarcity and urgency. "Only 25 left!" motivates quick action.
Max usage counts each individual claim, not unique customers. If one customer buys the box 3 times, that counts as 3 uses toward the limit.
Image
| What it is | A visual displayed on the box card in the app and CRM |
| Valid values | Any image from your asset library |
| Default | A default gift icon |
Select an image from your asset library. The system suggests the tag "surprise-box" to help you find relevant images quickly. The image appears as the box preview in both the CRM table and the customer app.
Recommendations:
- Use an image that suggests mystery and excitement (gift boxes, question marks, wrapped packages).
- Match the image theme to the box contents (a coffee-themed image for a coffee rewards box).
- Keep images consistent across your boxes for a professional look.
Active / Inactive Toggle
| What it is | Controls whether the box is available |
| Valid values | Active or Inactive |
| Default | Active |
When Active: The box appears in the points shop (if it has a price) and can be awarded as a reward.
When Inactive: The box is hidden from customers. It can no longer be purchased or awarded. Boxes that customers already claimed are not affected.
Deactivating is reversible. Use it to:
- Temporarily remove a box between seasonal rotations.
- Pause a box while you adjust its contents or probabilities.
- Retire a box without deleting it (preserving the configuration for reference).
Schedule Settings
Start Date and End Date
| What it is | A date range when the box is available |
| Valid values | Any date, or empty for no restriction |
| Default | No restriction (always available) |
Use dates for seasonal or promotional boxes. For example, a "Holiday Mystery Box" available only in December.
Valid Days
| What it is | Which days of the week the box is available |
| Valid values | Any combination of Mon-Sun, or empty for every day |
| Default | Every day |
Select specific days to create time-limited availability. A "Weekend Special Box" could be available only on Saturday and Sunday.
Available Hours
| What it is | The time window during which the box can be purchased |
| Valid values | A from/to time range, or "All day" |
| Default | All day |
Restrict availability to specific hours. A "Happy Hour Mystery Box" could be available only from 16:00 to 18:00.
Example schedule: A "Weekend Brunch Box" could be set to Saturday and Sunday only, from 9:00 to 14:00.
Reward Items
Reward items are the possible outcomes of opening a Surprise Box. Each box can have multiple reward items, and the customer receives exactly one when they open the box.
Adding Reward Items
After creating a Surprise Box, expand its row in the table and add the rewards customers can win:
- Expand the Surprise Box row by clicking on it.
- Click Add Item.
- Configure the reward (see fields below).
- Click Save.
- Repeat for each reward you want to include.
Reward Item Fields
Reward Type
| What it is | The kind of reward this item represents |
| Valid values | POINTS or VOUCHER |
| Default | None (required) |
- POINTS: The customer receives bonus loyalty points. Enter the number of points.
- VOUCHER: The customer receives a voucher. Select a voucher template from the dropdown (these are the templates you created in Vouchers).
Probability
| What it is | The chance of this reward being selected when the box is opened |
| Valid values | 0.1% to 100% |
| Default | None (required) |
The combined probabilities of all items in a box should add up to approximately 100%. If they do not, the system normalizes the probabilities proportionally -- but it is best practice to make them add up yourself for clarity.
If probabilities do not sum to 100%, the system will still work, but the actual chances will differ from what you entered. For example, if you have two items at 30% and 40% (total 70%), the actual probabilities become approximately 43% and 57%.
Show in Store
| What it is | Whether this reward is displayed as a preview before the customer purchases |
| Valid values | Checked or unchecked |
| Default | Unchecked |
When checked, this reward appears on the box card in the points shop. Customers can see what they might win before buying. Use this strategically:
- Show your best rewards to entice purchases.
- Hide common rewards to maintain the mystery.
- Show 2-3 items at most -- showing everything removes the surprise element.
How Probabilities Work
Probabilities determine the random selection when a customer opens the box. Understanding the math helps you design fair and engaging boxes.
The Basics
Each item has a probability expressed as a percentage. When a customer opens the box, the system generates a random number and selects the reward based on the probability distribution.
Example: A box with three items:
| Reward | Probability | Cumulative |
|---|---|---|
| 10 points | 60% | 0% - 60% |
| Free Coffee voucher | 30% | 60% - 90% |
| Free Meal voucher | 10% | 90% - 100% |
If the random number is 45, the customer gets 10 points (falls in the 0-60% range). If it is 82, they get the free coffee (60-90% range). If it is 95, they get the free meal (90-100% range).
Rarity Tiers
Design your boxes using a rarity system for the best customer experience:
| Rarity | Probability | Purpose | Example |
|---|---|---|---|
| Common | 40-60% | The baseline reward -- should still feel worthwhile | 10-20 bonus points |
| Uncommon | 25-35% | A step up -- noticeably better than common | 30-50 bonus points or a small voucher |
| Rare | 10-20% | Exciting -- the customer feels lucky | Free item voucher |
| Legendary | 3-10% | The jackpot -- memorable and share-worthy | Free meal voucher, large point bonus |
Never make the common reward feel like a waste. If a customer opens a box and gets "5 points" when the box cost them 50 points, they feel cheated and will never buy another box. Make the common reward at least 30-50% of the box's point cost so even the "worst" outcome feels acceptable.
Recommended Distributions
| Strategy | Vibe | Common | Uncommon | Rare | Legendary |
|---|---|---|---|---|---|
| Generous | Everyone wins big | 30% | 35% | 25% | 10% |
| Balanced | Fair and fun | 50% | 30% | 15% | 5% |
| Conservative | Rare items feel truly rare | 60% | 25% | 12% | 3% |
For your first box, start with the Balanced strategy. Adjust based on customer feedback and redemption data.
Purchasable vs. Reward-Only Boxes
Surprise Boxes support two modes depending on whether you set a price:
| Mode | Price field | How customers get it | Shows in shop? |
|---|---|---|---|
| Purchasable | Set a point value (e.g., 50) | Customer buys it from the store using points | Yes |
| Reward Only | Left empty | Given as a reward from challenges or Battle Pass tiers | No |
When to use each mode:
- Purchasable: When you want an always-available gamified spending option in your points shop. Gives customers something fun to do with their points besides buying vouchers.
- Reward Only: When you want the box to feel exclusive. "You can't buy this -- you can only earn it." Works especially well as a Battle Pass top-tier reward or a hard challenge reward.
Consider creating both: a cheaper purchasable "Everyday Mystery Box" for the shop, and a premium reward-only "VIP Box" that can only be earned through challenges or the Battle Pass. This creates a clear value hierarchy.
Frequently Asked Questions
Can I change probabilities after launch?
Yes. You can edit reward items and their probabilities at any time. Changes take effect immediately for the next customer who opens the box. Customers who already opened the box are not affected -- their result was determined at the time of opening. However, be cautious about making dramatic changes if customers have already purchased boxes expecting certain odds.
What if a customer gets the same item twice?
There is no duplicate protection. Each box opening is an independent random event. A customer could open two boxes and get the same reward both times. This is similar to how any random system works (rolling dice, drawing cards with replacement). If you want to reduce the feeling of repetition, include more reward items in the box.
How do I make a rare item feel special?
Several techniques make rare rewards feel exciting:
- Low probability: 3-5% creates genuine rarity. The customer knows they got lucky.
- High value: The rare reward should be significantly more valuable than common ones. A free meal vs. 10 bonus points is a clear distinction.
- Show it in the store preview: Use the "Show in Store" toggle to display the rare reward on the box card. Customers see what they could win, which makes getting it feel like hitting a jackpot.
- Name it evocatively: "Chef's Special" or "Grand Prize" sounds more special than "Voucher #4".
Can a customer open a box and not like the result?
No. Once a box is opened, the result is final. There are no refunds, re-rolls, or exchanges. This is by design -- the randomness is the core mechanic. Make sure all your reward items are genuinely valuable (even the common ones) so customers never feel like they "lost."
What happens if I delete a voucher used in a box?
If a voucher template used as a reward item is deleted or deactivated, customers who roll that reward will not receive a functional voucher. To avoid this, always check your Surprise Box reward items before deactivating or deleting voucher templates. Update the reward item to point to a different voucher, or remove the item and adjust probabilities.
How many items should a box have?
3-5 items is the sweet spot. Fewer than 3 feels predictable (the "mystery" is thin). More than 5 makes the probability math complex and dilutes each item's impact. For most restaurants:
- 3 items: Simple and clear. Good for your first box. One common, one uncommon, one rare.
- 4 items: Adds variety without complexity. Common, uncommon, rare, legendary.
- 5 items: Maximum recommended. Two commons, one uncommon, one rare, one legendary.
Does the customer see probabilities?
No. Customers see the reward items marked as "Show in Store" but not their probabilities. The mystery of not knowing the odds is part of the excitement. They can infer rarity from the rewards themselves (a free meal is obviously rarer than 10 points), but exact numbers are not shown.
What happens when max usage is reached?
The box becomes unavailable. It disappears from the points shop and can no longer be awarded as a reward. Boxes already claimed by customers are not affected. To make the box available again, either increase the max usage or create a new box.
Can I see which rewards customers received?
Individual box results appear in the customer's transaction history (visible in the User Info panel in the CRM). You can see that a customer spent points on a Surprise Box and what they received. There is no aggregate analytics view showing the distribution of all outcomes across all customers.
Are Surprise Box rewards and normal points shop purchases tracked differently?
Yes. In the transaction history, Surprise Box purchases show as type Surprise Box with the point cost as a REDUCE transaction. The reward (if it is points) shows as a separate ADD transaction. If the reward is a voucher, it appears in the customer's voucher wallet.
Troubleshooting
Box not appearing in the shop
Symptoms: You created a box but customers cannot find it.
Checklist:
- Is it Active? Inactive boxes are hidden.
- Does it have a price? Reward-only boxes (no price) do not appear in the shop by design.
- Check the schedule dates. If the start date is in the future or end date has passed, the box is not available.
- Check valid days and hours. The box might only be available on certain days or times.
- Is max usage reached? If all claims have been used, the box is no longer available.
- Does it have reward items? A box with zero reward items may not display properly.
Probabilities seem wrong
Symptoms: Customers seem to be getting certain rewards more or less often than expected.
Possible causes:
- Probabilities do not sum to 100%. Check the total. If they sum to more or less than 100%, the system normalizes them, which shifts the actual odds.
- Small sample size. With random systems, you need hundreds of opens to see the probabilities converge on the expected values. 10 opens is not enough to judge.
- Perception bias. Customers remember rare wins and forget common ones. The system is random -- streaks and clusters are normal.
Customer claims they did not receive a reward
Symptoms: A customer says they opened a box but did not get anything.
Investigation steps:
- Check the customer's transaction history in the CRM. Every box opening creates a transaction.
- If the reward was a voucher, check the customer's voucher wallet. It should appear there.
- If the reward was points, check the customer's balance. The points should be reflected.
- If the reward voucher template was inactive or deleted, the voucher may not have been delivered properly.
- If you cannot find the transaction, the box opening may not have completed (network issue on the customer's side). The customer's points should not have been deducted in this case.
Design Guide
Your First Box
Start simple. Create one box with 3-4 items:
| Item | Type | Probability | Show in Store |
|---|---|---|---|
| 10 bonus points | Points | 50% | No |
| 30 bonus points | Points | 30% | No |
| Free Coffee voucher | Voucher | 15% | Yes |
| Free Dessert voucher | Voucher | 5% | Yes |
Price it at 30-40 points. This gives customers a fun way to spend points with a real chance of winning something exciting.
Building a Box Lineup
Once you are comfortable with one box, create a tiered lineup:
| Box | Price | Reward quality | Target customer |
|---|---|---|---|
| Starter Box | 20 points | Mostly small point rewards, one decent voucher | New customers, casual visitors |
| Standard Box | 50 points | Mix of points and vouchers, one good voucher | Regular customers |
| Premium Box | 100 points | Higher point rewards, better vouchers, rare jackpot | Loyal customers with large point balances |
| VIP Box | Reward only | Best vouchers, highest point rewards | Challenge/Battle Pass reward only |
Seasonal Rotation
Keep boxes fresh by rotating them:
- Monthly: Retire the previous month's box and launch a new one with different rewards.
- Seasonal: Create themed boxes (Summer Box, Holiday Box, Valentine's Box) with themed voucher rewards.
- Limited edition: Low max usage (25-50) boxes that sell out quickly, creating urgency and FOMO.
Scheduling Ideas
| Box | Schedule | Rewards |
|---|---|---|
| Weekday Lunch Surprise | Mon-Fri, 11:00-14:00 | Lunch vouchers, bonus points |
| Weekend Special | Sat-Sun, all day | Premium vouchers, large point bonuses |
| Happy Hour Mystery | Daily, 16:00-18:00 | Drink vouchers, small point rewards |
| Holiday Box | Limited dates, all day | Exclusive seasonal vouchers |
Best Practices
Make Common Rewards Worthwhile
The most important rule: the worst possible outcome should still feel acceptable. If a customer pays 50 points and gets 5 points back, they feel scammed. If they get 20 points back, they think "not bad, I'll try again." The floor matters more than the ceiling.
Show the Best Rewards
Enable "Show in Store" for 1-2 of your best reward items. Seeing "Could win: Free Meal!" on the box card drives purchases. But do not show everything -- maintain mystery.
Price Below Expected Value
Calculate the expected value of your box (sum of each reward's value multiplied by its probability). Price the box 20-40% below the expected value. This ensures the box feels like a good deal on average, even though individual outcomes vary.
Example calculation:
| Reward | Value | Probability | Expected contribution |
|---|---|---|---|
| 10 points | 10 pts | 50% | 5.0 pts |
| 30 points | 30 pts | 30% | 9.0 pts |
| Free Coffee (worth ~40 pts) | 40 pts | 15% | 6.0 pts |
| Free Meal (worth ~100 pts) | 100 pts | 5% | 5.0 pts |
| Total expected value | 25.0 pts |
With an expected value of 25 points, pricing the box at 20 points makes it feel like a good deal.
Monitor and Adjust
After launching a box:
- Watch how quickly max usage is consumed. Too fast? You priced it too low or the rewards are too good. Too slow? The price is too high or rewards are not exciting enough.
- Check if customers are buying repeatedly. Repeat purchases mean the box is engaging.
- Listen to customer feedback about reward quality. Adjust common reward values if people feel disappointed.
Related Pages
- Create Your First Surprise Box -- Step-by-step tutorial
- Points System -- How customers earn points to buy boxes
- Vouchers -- Voucher templates used as box rewards
- Challenges -- Challenges that award Surprise Boxes
- Battle Pass -- Battle Pass tiers that award Surprise Boxes
- Choosing the Right Tool -- Compare all loyalty features