Containers with fixed contents in Economy v2

Economy v2 is now Generally Available. For support and feedback, go to the PlayFab Forum.

Economy v1 (Legacy) had a built-in Containers feature—special catalog items that, when opened, granted their contents to the player’s inventory. Economy v2 doesn’t include containers as a native item type, but you can achieve the same behavior for fixed-contents containers (containers that always grant the same items) by using a combination of virtual currency and bundles.

How it works

The pattern uses three Economy v2 building blocks:

A virtual currency (or stackable item) that represents the container itself—for example, “Treasure Chest Token.”
A Bundle priced at 1 of that currency, containing the items the container should grant.
A purchase call where the player spends 1 token to buy the bundle, which automatically unpacks and grants the items.

From the player’s perspective, they receive a token (via gameplay rewards, store purchases, and so on), then “open” it to get the items inside—exactly how V1 containers worked.

Prerequisites

A PlayFab developer account.
A Title created in Game Manager.
At least one published catalog item that you want the container to grant.

Step 1: Create a virtual currency for the container

Create a virtual currency that represents the container. Each unit of this currency acts as one unopened container.

Game Manager

Go to Economy > Catalog (V2) > Currency.
Select New currency.
Set the Title to a descriptive name, such as Treasure Chest.
Set the FriendlyId to a short code, such as tc.
Select Save and publish.

REST API

Call CreateDraftItem:

{
  "Item": {
    "CreatorEntity": {
      "Id": "{{TitleID}}",
      "Type": "title"
    },
    "Type": "currency",
    "AlternateIds": [
      {
        "Type": "FriendlyId",
        "Value": "tc"
      }
    ],
    "Title": {
      "NEUTRAL": "Treasure Chest"
    },
    "Description": {
      "NEUTRAL": "A treasure chest that can be opened to reveal its contents."
    },
    "StartDate": "2023-07-27T00:00:00.000Z"
  },
  "Publish": true
}

Step 2: Create a bundle priced at one container token

Create a bundle that contains the items you want the container to grant. Price the bundle at exactly one unit of the container currency.

Game Manager

Go to Economy > Catalog (V2) > Bundles.
Select New bundle.
Set the Title to describe the container’s contents, such as Treasure Chest Contents.
Under Items, add the items and quantities you want the container to grant—for example, 1 Legendary Sword and 100 Gold.
Under Price, set the price to 1 of your container currency (Treasure Chest).
Select Save and publish.

REST API

Call CreateDraftItem:

{
  "Item": {
    "Type": "bundle",
    "Title": {
      "NEUTRAL": "Treasure Chest Contents"
    },
    "StartDate": "2023-07-27T00:00:00.000Z",
    "ItemReferences": [
      {
        "Id": "{{LegendarySwordID}}",
        "Amount": 1
      },
      {
        "Id": "{{GoldCurrencyID}}",
        "Amount": 100
      }
    ],
    "PriceOptions": {
      "Prices": [
        {
          "Amounts": [
            {
              "ItemId": "{{TreasureChestCurrencyID}}",
              "Amount": 1
            }
          ]
        }
      ]
    }
  },
  "Publish": true
}

When a player purchases this bundle, the bundle is automatically unpacked—the individual items go directly to the player’s inventory.

Step 3: Grant container tokens to players

Grant the container currency to players through any mechanism that fits your game design:

Gameplay rewards—Grant tokens after completing a level, quest, or achievement by using AddInventoryItems.
Store purchases—Sell the container token in a Store for another virtual currency or real money.
Battle pass / seasonal rewards—Include the token as a reward tier.

Example using AddInventoryItems to grant three Treasure Chest tokens:

{
  "Entity": {
    "Type": "title_player_account",
    "Id": "{{PlayerID}}"
  },
  "Item": {
    "Id": "{{TreasureChestCurrencyID}}"
  },
  "Amount": 3
}

Step 4: Open the container

When the player wants to open a container, call PurchaseInventoryItems to buy the bundle with one container token:

{
  "Entity": {
    "Type": "title_player_account",
    "Id": "{{PlayerID}}"
  },
  "Item": {
    "Id": "{{TreasureChestContentsBundleID}}"
  },
  "Amount": 1,
  "PriceAmounts": [
    {
      "ItemId": "{{TreasureChestCurrencyID}}",
      "Amount": 1
    }
  ]
}

After a successful call, the player’s inventory is updated: One Treasure Chest token is deducted and the bundle’s contents (one Legendary Sword + 100 Gold) are added.

Multiple container types

Create multiple container types by repeating this pattern. For example:

Container	Currency (FriendlyId)	Bundle contents
Treasure Chest	`tc`	One Legendary Sword + 100 Gold
Supply Crate	`sc`	Five Health Potions + 3 Mana Potions
Premium Box	`pb`	One Rare Mount + 500 Gold + 50 Gems

Each container type has its own currency and bundle.

Using a Store for container purchases

Use a Store to override the container bundle’s price. By using a store, you can offer the same container at different prices in different contexts (for example, a discounted “open” cost during an event):

{
  "Item": {
    "Type": "store",
    "Title": {
      "NEUTRAL": "Event Store"
    },
    "ItemReferences": [
      {
        "Id": "{{TreasureChestContentsBundleID}}",
        "Amount": 1,
        "PriceOptions": {
          "Prices": [
            {
              "Amounts": [
                {
                  "ItemId": "{{TreasureChestCurrencyID}}",
                  "Amount": 1
                }
              ]
            }
          ]
        }
      }
    ]
  },
  "Publish": true
}

Then pass the StoreId when purchasing:

{
  "Entity": {
    "Type": "title_player_account",
    "Id": "{{PlayerID}}"
  },
  "Item": {
    "Id": "{{TreasureChestContentsBundleID}}"
  },
  "Amount": 1,
  "PriceAmounts": [
    {
      "ItemId": "{{TreasureChestCurrencyID}}",
      "Amount": 1
    }
  ],
  "StoreId": "{{EventStoreID}}"
}

Limitations

This pattern works for containers with fixed, deterministic contents. If you need randomized loot (where the contents vary each time a container is opened, similar to V1 containers paired with drop tables), see the Drop tables and randomized loot tutorial. This tutorial uses Azure Functions to:

Subtract the container token from the player’s inventory.
Run your weighted random selection logic.
Grant the resulting items through the inventory APIs.

XBOX Services

PlayFab

How it works

Prerequisites

Step 1: Create a virtual currency for the container

Game Manager

REST API

Step 2: Create a bundle priced at one container token

Game Manager

REST API

Step 3: Grant container tokens to players

Step 4: Open the container

Multiple container types

Using a Store for container purchases

Limitations

See also

​How it works

​Prerequisites

​Step 1: Create a virtual currency for the container

​Game Manager

​REST API

​Step 2: Create a bundle priced at one container token

​Game Manager

​REST API

​Step 3: Grant container tokens to players

​Step 4: Open the container

​Multiple container types

​Using a Store for container purchases

​Limitations

​See also

How it works

Prerequisites

Step 1: Create a virtual currency for the container

Game Manager

REST API

Step 2: Create a bundle priced at one container token

Game Manager

REST API

Step 3: Grant container tokens to players

Step 4: Open the container

Multiple container types

Using a Store for container purchases

Limitations

See also