How to Use World Wallet & Payments API: 2026 Seasonal Promos

TL;DR

World Wallet and the Payments API are two sides of a seasonal promotion economy in Highrise. The Payments API handles incoming Gold from In-World Purchases (event passes, bundles, boosts), while World Wallet manages outgoing Gold rewards (prize pools, daily bonuses, leaderboard payouts). You also need Storage or Inventory to track what each player bought, earned, and claimed. The best seasonal promotions combine all three layers with server-side validation, clear pricing, reward caps, and a free path for every player.

What Are World Wallet and Payments API?

These two tools solve different problems, and confusing them is one of the most common mistakes new Highrise creators make.

World Wallet is the world-level Gold management system. It lets creators store Gold for a world and award that Gold to players through world mechanics. Think of it as the reward budget: the pool of Gold you draw from when paying out prizes, daily bonuses, or achievement rewards. The official World Wallet documentation describes configurable settings like minimum balance alerts and maximum award amounts.

Payments API is the purchase system. It manages In-World Purchases (IWPs), including prompting players to buy products, handling purchase events on the server, and acknowledging completed transactions. The Payments API documentation describes the full purchase flow: set up a PurchaseHandler, grant items or rewards, and call AcknowledgePurchase after fulfillment.

The simplest way to remember the difference: Payments API brings Gold in. World Wallet sends Gold out.

Seasonal promotions need both. One collects revenue from optional paid offers. The other funds the rewards that keep players coming back. Without understanding how to use World Wallet and Payments API to run seasonal promotions together, creators either leave money on the table or build events that feel hollow.

Term	Plain-English Meaning	Role in a Seasonal Promotion
World Wallet	The world’s reward wallet	Prize pools, daily bonuses, milestone rewards
Payments API	The purchase system	Event passes, boosts, bundles, special access
In-World Purchase (IWP)	The product players buy	Halloween bundle, winter pass, fashion ticket
Storage	Memory for event progress	Daily claims, quest completion, leaderboard scores
Inventory	Transactional item/currency layer	Event tokens, consumables, owned rewards

How Seasonal Promotions Work in Highrise Worlds

Seasonal promotions are not just decoration. In mobile gaming broadly, live events and promotions are core retention tools. Moloco’s 2025 research found that top gaming apps improved install-to-payer conversion and lifetime value by up to 6% in D30/D90 cohorts, with improvements tied directly to live operations including in-game events and promotions. That study analyzed 4 billion installs and $2 billion in IAP revenue across 100 leading mobile gaming advertisers. source

For Highrise creators, a seasonal promotion has four parts:

1. A reason to visit. A Halloween hunt, winter gifting festival, fashion contest, or weekend challenge. The theme gives players a reason to show up. Tying events to real-world seasons or Highrise news and announcements creates natural urgency.

2. A free reward path. Players earn event points, seasonal currency, badges, or small Gold rewards through play. This matters more than most creators realize. Practitioners on Reddit report that earning Gold as a free player feels slow and unreliable, and that buying Gold is often perceived as the only realistic path. source If your seasonal promotion has no free path, it will feel like a cash wall to most of your audience.

3. Optional paid offers. Premium bundles, event passes, boosts, special cosmetics, VIP area access, or bonus entries. These are sold through the Payments API as In-World Purchases.

4. A clear reward moment. A limited shop, leaderboard payout, final prize draw, or post-event claim window. Players need to see the finish line.

This loop, sell, track, reward, repeat, is the foundation for every seasonal promotion pattern.

What to Use the Payments API For

The Payments API is your incoming purchase rail. During a seasonal promotion, use it to sell limited-time products that enhance the event experience without replacing it.

Good seasonal IWP candidates include:

• Seasonal passes that unlock bonus objectives or premium reward tracks
• Event bundles with exclusive cosmetics or items from the Highrise catalog
• Temporary boosts that accelerate point earning
• Special area access (a VIP lounge, backstage zone, or hidden room)
• Paid mini-game entries where appropriate
• Convenience unlocks like streak catch-up tokens

Technical essentials

Products are created in the Creator Portal with unique product IDs. Use readable IDs like winter_pass_2026 or ghost_boost_small so your scripts stay maintainable.

The purchase flow works like this:

1. Show in-world UI that explains the product, its price, and what the player gets.
2. Call PromptPurchase on the client to start the purchase flow.
3. Handle the purchase server-side through PurchaseHandler.
4. Validate the product ID and grant the correct reward.
5. Save the entitlement in Storage or Inventory.
6. Call AcknowledgePurchase only after fulfillment is complete.

The advanced Payments guide explicitly warns that the PromptPurchase callback should not be trusted as final proof of payment because it can produce false positives. Purchases must be validated on the server through PurchaseHandler. This is not a suggestion. It is the single most important security rule when using World Wallet and Payments API to run seasonal promotions.

What to Use World Wallet For

World Wallet is the outgoing reward budget. It funds the prizes and incentives that make your event feel worthwhile.

The Wallet API documentation lists several use cases that map directly to seasonal promotions:

• Daily login Gold bonuses (the API even includes example logic for once-per-day rewards)
• Competition and event prize pools
• Achievement rewards for completing seasonal objectives
• Random surprise rewards with caps to prevent overspending
• Crew or team milestone rewards
• End-of-season leaderboard payouts
• Creator-funded giveaways to celebrate community milestones

Technical cautions

Wallet calls are server-side only, rate-limited, and available only for published worlds with monetization enabled. Transfers require a positive amount and sufficient Gold balance, and they are final. You cannot reverse a wallet transfer.

Error handling should account for:

• InsufficientResources (wallet is empty or low)
• RequestThrottled (too many calls too fast)
• InternalError (platform issue)
• UserNotFound (invalid or missing player)

The WalletError documentation covers each of these. Before every reward transfer, check your wallet balance. Use the minimum balance alert setting to get warned before your reward pool runs dry mid-event.

The Missing Layer: Storage and Inventory

A seasonal promotion fails if it cannot remember what happened. A player buys an event pass, leaves, comes back the next day, and the world has forgotten the purchase. This is not hypothetical. A thread on the Highrise Create forum shows a creator asking why something they sold did not persist, and the response explains that creators need both in-world purchase UI and a way to store the item against the player so ownership is recognized later. source

This is why Storage and Inventory are the hidden third piece of any seasonal promotion.

Storage persists data permanently across world restarts, player sessions, and server updates until explicitly deleted. The Storage API documentation says it is commonly used for player progress, preferences, world state, leaderboards, and high scores. For seasonal promotions, use Storage to track:

• Daily login claim dates
• Event scores and quest progress
• “Has claimed reward” flags
• Cooldowns and rate limits
• Event start/end states
• Leaderboard totals

Inventory is better when the promotion grants items, consumables, event tokens, or virtual goods that need transaction-like consistency. The Inventory API documentation describes operations including Give, Take, Move, Reserve, and Release. Use Inventory for event tokens, purchased items, consumable boosts, and limited rewards.

Layer	Tool	What It Tracks in a Seasonal Event
Purchase	Payments API	Incoming Gold from IWP sales
Reward budget	World Wallet	Outgoing Gold for prizes and incentives
Entitlement	Inventory	Event tokens, consumables, owned items
Progress	Storage	Quest status, daily claims, leaderboard scores
Measurement	IWP analytics/logs	Sales volume, revenue, top products

Example Seasonal Promotion Patterns

These patterns show how to use World Wallet and Payments API to run seasonal promotions in practice. Each one combines the purchase rail, reward budget, and state tracking into a complete loop.

Pattern 1: Halloween Hunt

Concept: Players collect seasonal points by completing tasks, finding hidden objects, or fighting cooperative bosses.

Highrise’s own Boo Bash event used Ectoplasm as a seasonal currency, cooperative ghost-popping mechanics, Phantom bosses, and exclusive Halloween rewards. source Creators can build similar loops at smaller scale.

• Payments API sells: Premium Halloween bundle, temporary event boost, haunted area access
• World Wallet funds: Daily Gold bonus for first completion, boss-fight contribution rewards, end-of-event leaderboard prize
• Storage/Inventory tracks: Seasonal points, boss participation, daily claim flag, owned event bundle

Pattern 2: Winter Gifting Festival

Concept: Players earn seasonal currency by gifting, visiting rooms, or interacting with others.

Highrise’s Wintery Wish season used Cheer as a seasonal currency, a Cheermart shop, Wishboxes, gifting mechanics, room buffs, and cooperative swarms. The season was explicitly framed around connection and small acts of generosity. source Engaging the Highrise community around gifting creates emotional value that pure purchases cannot replicate.

• Payments API sells: Gift bundle, premium ornament, special room buff, winter cosmetic
• World Wallet funds: Random Gold gifts, room-wide reward drops, gifting milestone payouts
• Storage/Inventory tracks: Who sent/received gifts, claim status, seasonal currency balance, gift cooldowns

Pattern 3: Fashion Contest Weekend

Concept: Players submit outfits, vote, attend shows, and compete for prizes. If your community runs user design contests, a seasonal fashion event is a natural extension.

• Payments API sells: Premium runway pass, backstage access, limited fashion item
• World Wallet funds: Winner prizes, participation raffles, judge-selected awards
• Storage/Inventory tracks: Entries, votes cast, vote caps, reward claim status

Trust note: Do not let paid purchases guarantee victory. Let them enhance presentation or access. Pay-to-win voting destroys community trust fast.

Pattern 4: Daily Login Streak

Concept: Players return each day for a seasonal reward that grows over time.

Mistplay’s 2025 Mobile Gaming Loyalty Index found that 64% of players cite daily engagement bonuses as an important retention driver, and 50% cite regular in-game events. source

• Payments API sells: Optional premium streak track, catch-up token, seasonal bundle
• World Wallet funds: Small daily Gold rewards, milestone Gold payouts at days 7, 14, and 21
• Storage tracks: Last login date, streak count, missed days, claimed reward tier

A daily login event is the best first seasonal promotion for new creators. It is simple to monitor, easy to budget, and teaches you how World Wallet and Payments API interact without the complexity of a multi-currency system.

Pattern 5: Weekend Leaderboard Tournament

Concept: Players compete during a 48-hour or 72-hour window, with fixed prizes for top performers.

• Payments API sells: Cosmetic supporter pack, optional boost (that does not break competitive fairness)
• World Wallet funds: Fixed prize pool, top-rank payouts, random participation prizes
• Storage tracks: Score, event window, anti-repeat rules, prize claim status

Fairness lesson: Highrise’s Wintery Wish changed its Blitz reward system from team-total rewards to individual contribution rewards because players said idle participants being rewarded felt unfair. source For any competitive event, reward contribution, not mere presence.

Promotion Architecture: The Safe Flow

Here is the complete flow for running a seasonal promotion safely. This is the architecture that ties together every concept above.

Step 1: Plan the event economy. Decide what is free, what is paid, what rewards cost, daily and weekly caps, and what happens after the season ends.

Step 2: Create IWP products. Set up product IDs in Creator Portal. Use readable, versioned IDs.

Step 3: Build purchase UI. Show the item name, price, duration, and exactly what the player gets. Never let preview, inspect, or close buttons sit dangerously close to purchase buttons.

Step 4: Handle purchases server-side. Use PurchaseHandler to validate the product ID, grant the correct reward, save the entitlement in Storage or Inventory, and acknowledge only after fulfillment.

Step 5: Reward players from World Wallet. Check wallet balance first. Apply caps and cooldowns. Transfer Gold from server-side logic only. Log outcomes.

Step 6: Track everything. Use Storage for progress and claims. Use Inventory for items and consumables. Use wallet logs (viewable in the Logs tab) and IWP analytics to review sales and reward flow.

Step 7: Close the season cleanly. Stop purchase prompts. Keep the redemption window open briefly if desired. Pay prizes. Archive event data. Announce winners and the next event. Check platform status before launching any time-sensitive event to avoid starting during an outage.

Safety, Fairness, and Trust Checklist

Before launching a seasonal promotion, confirm every item on this list.

• The event has a free participation path
• Paid offers are optional and clearly described
• Purchase buttons are not placed near preview, close, or inspect buttons in a confusing way
• Product IDs are mapped to exact rewards on the server
• PromptPurchase is not treated as final payment proof
• PurchaseHandler validates product ID and grants rewards server-side
• AcknowledgePurchase is called only after fulfillment
• Storage or Inventory records ownership, progress, and claims
• World Wallet balance is checked before every transfer
• Daily, weekly, and per-player reward caps are in place
• Leaderboard prizes use contribution-based rules, not idle-friendly ones
• The end date and redemption rules are visible to players
• The creator has checked the latest IWP revenue-share terms in Creator Portal (public documentation currently shows conflicting percentages, so verify before budgeting)
• Pricing and purchase terms are clear for players in all target regions

This is not just about good design. Regulators are watching. The FTC finalized a $245 million order against Epic Games over allegations that Fortnite used dark patterns to trick players into unwanted purchases, and the order prohibits charging consumers without affirmative consent. source The European Commission’s CPC Network principles state that real-world money prices should be clearly displayed when virtual currency or digital content is offered for sale, and that practices obscuring costs should be avoided. source

Clear pricing and honest purchase flows protect both your players and your reputation as a creator.

Common Mistakes When Running Seasonal Promotions

Trusting the client callback as proof of payment

The advanced Payments guide warns that the PromptPurchase paid callback can be a false positive. If you grant rewards based on the client callback instead of PurchaseHandler, players could receive products they never paid for. Always validate server-side.

Forgetting persistence

If your world grants an event pass but does not store ownership, players lose access after a restart or new session. Storage persists across world restarts and player sessions. Inventory handles item operations through transactions. Use at least one of them for every entitlement your promotion creates.

Overpaying from the World Wallet

Wallet transfers are final and cannot be reversed. If a bug or logic error sends Gold to the wrong player, too many players, or in the wrong amount, you cannot undo it. Use maximum award settings, daily caps, per-player cooldowns, and balance checks before every transfer.

Running a promotion that feels paywalled

One Reddit thread about Highrise “spin grabs” includes complaints about high prices and the feeling that the game has become too monetized. source Every seasonal event should have at least one meaningful free loop. Paid offers should accelerate or decorate the experience, not replace it.

Obscuring real cost

Do not hide the actual Gold price behind confusing currency bundles or misleading UI. Use clear purchase buttons, plain descriptions, and visible pricing. If you use randomized rewards, communicate the mechanics clearly. Prefer guaranteed progress tracks and milestone rewards over pure chance.

Designing rewards that encourage idling

For competitive events, reward what players do, not how long they stand in a room. Highrise learned this when the Wintery Wish Blitz system was changed because idle participation felt unfair to active players.

Publishing unverified revenue-share percentages

Official Highrise public documentation currently shows conflicting IWP revenue-share figures across different pages. Do not budget your promotion based on a single page. Check the latest terms in Creator Portal and official monetization documentation before planning your event economy.

Why Newness Matters in Seasonal Events

An empirical study of free-to-play mobile games found that players who acquired new virtual items in one week tended to play longer and make more purchases the following week. source This has a direct implication for seasonal promotions: do not just discount an existing product. Give players something new to chase, unlock, show off, or share.

Seasonal-exclusive items, limited-time cosmetics, event-only badges, and fresh room decorations all tap into this novelty effect. If you are looking for creative direction, submit ideas through Highrise Ideas to gather community feedback on what your next seasonal theme should be.

Before You Budget: A Note on Revenue Share

The Payments API documentation and the In-World Purchases documentation show different revenue-share percentages for IWP earnings. The advanced Payments guide states one figure, while the Earning Overview and Accepting Gold Payments pages state another.

The safe approach: check the current Creator Portal terms before budgeting any IWP-based event. Revenue-share terms can change, and your promotion’s economics depend on getting this number right.

Start Building Seasonal Events in Highrise

Seasonal promotions can support engagement, repeat visits, social sharing, and monetization, but results depend on traffic, retention, offer quality, and player trust. The creators who do well are the ones who combine the Payments API’s purchase rail with World Wallet’s reward rail while tracking everything through Storage and Inventory.

If you are ready to start building, download Highrise on iOS, Android, or desktop. For desktop builders and players, Highrise on Steam offers cross-platform access with a single account and inventory.

For more guides, creator updates, and platform news, check the Highrise blog.

Frequently Asked Questions

What is the difference between World Wallet and the Payments API?

The Payments API handles purchases from players. World Wallet handles Gold stored for the world and awarded back to players. Payments API is the incoming monetization rail; World Wallet is the outgoing reward rail. To run a seasonal promotion, you need both: Payments API for selling optional event products and World Wallet for funding prizes and daily bonuses.

Can I use World Wallet for daily login rewards?

Yes. The Wallet API documentation lists daily login bonuses as a specific use case and includes example logic for giving a player Gold once per day. Combine it with Storage to track the last claim date and prevent duplicate rewards.

Should I fulfill purchases on the client or server?

Always on the server. The Payments guide states that payment-related scripts should be handled server-side, and the API requires server-side purchase handling through PurchaseHandler and acknowledgement through AcknowledgePurchase. The client-side PromptPurchase callback can produce false positives and should never be treated as proof of payment.

What should I store for a seasonal event?

Store player progress, claim status, purchase entitlements, cooldowns, leaderboard totals, and event-specific state. Storage persists across world restarts and player sessions, making it suitable for progress and claims. Inventory is better for item and currency transactions that need transactional consistency.

What is a good first seasonal promotion?

A daily login event with a small free reward, one optional seasonal bundle, and a simple leaderboard or milestone prize. It is easier to monitor than a complex multi-currency event, and it teaches you how World Wallet and Payments API work together in practice.

How do I avoid making the promotion feel like a cash grab?

Give players a meaningful free path. Show exact rewards. Use guaranteed milestones instead of relying entirely on chance-based mechanics. Cap spending pressure. Avoid confusing purchase UI. Make paid offers additive rather than mandatory. Community discussions on Reddit consistently show that players are sensitive to expensive-feeling promotional mechanics, and trust is hard to rebuild once lost.

What happens if my World Wallet runs out of Gold mid-event?

Wallet transfers require sufficient Gold balance. If the wallet is empty, transfer calls will fail with an InsufficientResources error. Use minimum balance alerts to get warned before your pool runs dry, and budget your reward caps so the total possible payout does not exceed your wallet balance. Transfers are final and cannot be reversed, so careful budgeting before the event starts is essential.

How do I know if my seasonal promotion is working?

Use wallet logs (available in the Logs tab of World Wallet) to review reward outflows. Check IWP analytics for total sales, total revenue, and top-selling products. Track player participation through Storage data. Compare daily active visitors, repeat sessions, and conversion rates against your pre-event baseline.