Collections

Important

Economy v2.0 Public Preview has released. Use these features to participate in the active development of our latest code, and provide feedback to the developers via the PlayFab Forum.

The Economy v2 Inventory service introduces the concept of collections that can add greater flexibility and support for your inventory needs. Collections are the mechanism that allows for a single player/PlayerId to have multiple inventories. This feature can be used to manage multiple inventories for different characters for the same player, having separate inventories for different platforms, and more!

Inventory API calls can take in a CollectionId parameter that specifies the collection/inventory to perform the action in. Creating a new collection is done by adding an item/stack to an unused CollectionId.

Managing Inventory Collections

GetInventoryCollectionIds

Using the GetInventoryCollectionIds API, you can get a list of CollectionIds for a given player. Players are limited to only accessing their own list of IDs. Title Entities can pass in an Entity parameter to indicate which player's inventory they wish to access.

An example GetInventoryCollectionIds request:

{
  "Entity": {
    "Type": "title_player_account",
    "Id": "1234ABCD"
  },
  "Count": 15,
  "ContinuationToken": "abc="
}

This request would return the following response:

{
  "data": {
  "CollectionIds": [
    "default".
    "main_character"
    ]
  }
}

Continuation Tokens

The ContinuationToken field that is returned from a search response can be passed into an inventory request to paginate through multiple counts of results.

Adding a New Inventory Collection

Creating a new collection for a player is done by performing any write request with a new CollectionId.

For example, the following AddInventoryItems request uses the collectionId main_character

{
    "Entity": {
        "Type": "title_player_account",
        "Id": "630287F4"
    },
    "CollectionId": "main_character",
    "Item": {
        "Id": "0b440353-bdbc-48d8-8873-f0988c1f9d8b",
    },
    "Amount": 10,
}

The above request would either create a brand new inventory collection of and add 5 of the item to it or add 5 to the existing main_character inventory collection if it already existed.

Note

Currently, APIs are the only way to Inventory Collections. Game Manager can currently only be used to view and add items to existing collections and create new collections. Additional functionality will be added in the future.

DeleteInventoryCollection

In the DeleteInventoryCollectionId API, you can define the CollectionId you wish to delete. This collection

An example DeleteInventoryCollectionIds request:

{
  "Entity": {
    "Type": "title_player_account",
    "Id": "1234ABCD"
  },
  "CollectionId": "main_character"
}

Warning

As of public preview, deleted CollectionIds cannot be used again and thus, a collection of the same CollectionId cannot be created again. This will be the behavior until additional delete functionality is implemented scheduled to come sometime in the future. As of now, extreme caution should be used when deleting CollectionIds.

Note

Currently, APIs are the only way to delete Inventory Collections. Game Manager can currently only be used to view and add items to existing collections. Additional functionality will be added in the future.

ExecuteInventoryOperations API

You can set a CollectionId parameter in the ExecuteInventoryOperations API. This parameter allows you to define the collection where you want the operations to be performed in.

An example ExecuteInventoryOperations request with stacks:

{
    "Entity": {
        "Type": "title_player_account",
        "Id": "630287F4"
    },
    "CollectionId": "main_character",
    "Operations": [
        {
            "Update": {
                "Item" {
                    "Id": "0b440353-bdbc-48d8-8873-f0988c1f9d8b",
                    "Amount": 10
                }
            }
        },
        {
            "Subtract": {
                "Item" {
                    "Id": "0b440353-bdbc-48d8-8873-f0988c1f9d8b",
                },
                "Amount": 5
            }
        }
    ]
}