Economy v2 Stores

Important

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

Stores are an excellent way to build upon and develop your in-game Economy. Stores are a special item type that hold a list of items and prices and allow you to override base catalog prices for items. Stores can be used to manage where items are purchaseable in your game, offer in-game discounts and promotions, and much more!

Creating a Store

To create a store, you must first make sure you have other published Catalog Items, Currency or UGC which you want to be accessible/purchaseable in your game. You can follow the steps in the Economy v2 Quickstart

GameManager

1. Navigate to Economy ↘️ Catalog (V2).

2. Under the Stores tab, select New Store.

Fill in the desired metadata, one of the key things to be setting is the items you wish to be available at this store and what prices you wish to override them to.

API

You can use the CreateDraftItem to create a store.

An example CreateDraftItem request to create a store:

{
  "Item": {
   "Type": "store",
    "Title": {
      "NEUTRAL": "My First Store",
    },
    "StartDate": "2022-09-07T00:00:00.00000000Z",
    "ItemReferences":[
      {
        "Id":"LaserSword",
        "Amount": 1,
        "PriceOptions": {
          "Prices": [{
            "Amounts": [{
              "ItemId": "Diamond",
              "Amount": 1
            }]
          }]
        }
      },
      {
      "Id":"WeaponBundle",
      "PriceOptions": {
        "Prices": [{
          "Amounts": [{
            "ItemId": "Gold",
            "Amount": 10
            },
            {
            "ItemId": "Silver",
            "Amount": 10
          }]
        }],
      },
    }]
   },
   "Publish": true
}

The above is a store that sells two items, the LaserSword and the WeaponBundle. Both items are existing catalog items with some existing base price as defined in the catalog. This store, overrides their existing prices and now offers the LaserSword for 1 Diamond and the WeaponBundle for 10 Gold and 10 Silver.

This would return a response that the store has been created and published:

{
  "code": 202,
  "status": "Accepted",
  "Item": {
    "Type": "store",
    "Id": "{{ItemID}}", 
    "Title": {
      "NEUTRAL": "My First Store",
    },
    ...
}

Note that Id that is now associated with our published store.

Note

To help simplify the concept, the item Ids have been swapped from GUIDs to easier to text items to better illustrate the utility of Stores.

Using a Store

Stores are used when players call the PurchaseInventoryItems API. When calling PurchaseInventoryItems One of the optional properties is a StoreId parameter where we can pass in the Store we use to apply to this purchase request.

An example PurchaseInventoryItems request using a store:

{
    "Entity": {
        "Type": "title_player_account",
        "Id": "{{ItemID}}"
    },
    "Item": {
        "Id": "LaserSword",
    },
    "Amount": 10,
    "PriceAmounts": [
        {
            "ItemId": "Diamond",
            "Amount": 1
        }
    ],
    "StoreId": "{{StoreID}}"
}

Note the StoreId passed into the purchase request and how the anticipated PriceAmount now matches the 1 Diamond Cost as set above in our store.

Searching a Store

Using the SearchItems API, one of the properties you can pass in is the Store parameter. This allows you to search within the context of a store. In addition to being able to check if an item exists in a particular store, it also can be used to display the overridden prices of the store's items/contents. You can also use the AlternateId of the store to search for it.

{
  "Search": "",
  "Filter": "ContentType eq 'weapons'",
  "Store": {
    "Id": "{{StoreID}}"
  },
}