Virtual Store

A virtual store is an in-game marketplace where players can acquire items, consumables, cosmetics, and other resources using various forms of currency. It supports purchases made with game currencies (such as gold or gems) as well as in-app purchases (IAPs) validated through Apple App Store and Google Play.

Virtual stores are defined in your Economy configuration JSON file under the store_items collection.

Store items #

A store is essentially a collection of items. Each item specifies its cost (currencies and/or SKU), the rewards granted on purchase, and optional metadata. Here’s an example of a PlasmaCorePack item:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

"PlasmaCorePack": {
    "category": "powerups",
    "cost": {
        "currencies": {
            "currencies": {},
            "sku": "com.example.item1" // in-app purchase
        }
    },
    "description": "Power your gear with concentrated plasma energy.",
    "name": "Plasma Core Pack",
    "reward": {
        "guaranteed": {
            "currencies": {
                "PlasmaCores": {
                    "min": 1 // the player receives just 1 of this item
                }
            }
        }
    },
    "additional_properties": {
        "limited": false // additional metadata
    }
}

The reward is what the player receives for purchasing the item. In this example, the player is guaranteed to receive PlasmaCores, which is defined separately in the Inventory system.

Think of rewards as the result of players taking a desirable action in your game, including store purchases. See Rewards to learn more about the different ways you can configure and deliver rewards to your players.

Purchases #

By default, store items can be purchased repeatedly as long as the player has sufficient currency or a valid receipt. The virtual store handles both game currency purchases and in-app purchases.

Game currency purchase vs in-app purchase #

The sku field in your store item configuration determines how the server processes the purchase:

Purchase flow #

The steps depend on whether the item is an in-app purchase or not.

In-app purchase:

1. Player selects an item from your store UI.
2. Client calls PurchaseIntent to record the selected item (optional, see below).
3. Client initiates platform purchase (Apple/Google/etc) and receives a receipt.
4. Client calls PurchaseItem with the item ID and receipt.
5. Server validates the receipt with the platform provider.
6. Server grants rewards to player.

Game currency:

1. Player selects an item from your store UI.
2. Client calls PurchaseItem with the item ID.
3. Server checks the player has sufficient balance and deducts the cost.
4. Server grants rewards to player.

Purchase intents #

Purchase intents disambiguate which store item to grant when multiple items share the same SKU. This is common with LiveOps or A/B testing, where you want the same price point in the app store but different rewards for different player segments.

For example, two items might both cost $0.99 and use SKU com.game.premium_100, but one gives 150 gems to new players while the other gives 100 gems to everyone else. When the app store returns a receipt for com.game.premium_100, the server needs to know which item to grant.

Call PurchaseIntent before initiating the purchase to record which item the player selected. The server uses this to resolve the correct item when processing the receipt. Intents expire after 10 minutes.

If each store item has a unique SKU, you don’t need to call PurchaseIntent.

Testing in-app purchases in Unity #

The allow_fake_receipts option in your economy configuration only applies when you’re using the Unity Editor. When enabled, receipts containing the string “fake receipt” or “FakeReceipt” bypass validation entirely.

This setting does not affect:

• Google Play test purchases or license testing
• Apple TestFlight or sandbox purchases

For real device testing, configure your IAP credentials and use the platform’s testing tools.

Customizing store behavior #

The basic store configuration supports simple, repeatable purchases. For more advanced scenarios, use the Personalizer to dynamically modify store data based on player state:

• One-time offers: For items purchasable only once per player (like a “Starter Pack”), use the Personalizer to hide items after purchase. See One-time store offers for a complete implementation guide.
• Player-specific offers: Show different prices, rewards, or items to different player segments (new players, VIPs, players at certain levels). Combined with Satori audiences, you can run A/B tests or target specific groups with tailored offers.

Store types #

When making in-app purchases, the server needs to know which platform’s receipt validation to use. You specify this when initializing the Economy system on the client. Refer to each client’s SDK guide for more details (for example: Unity Economy SDK, Unreal Economy SDK).

EconomyStoreType values #

Virtual Store configuration #

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

{
  "store_items": {
    "<itemId>": {
      "name": "Item Name",
      "description": "Item description",
      "category": "optional_category",
      "cost": {
        "currencies": {},
        "sku": "optional_sku"
      },
      "reward": {},
      "additional_properties": {},
      "disabled": false
    }
  }
}

Store item cost #

Related resources #

• Personalizer
• In-app purchase validation
• Implement one-time store offers
• Build an in-game store
• Server framework function reference