Documentation

UnlockContainerInstance

Opens the specified container, with the specified key (when required), and returns the contents of the opened container. If the container (and key when relevant) are consumable (RemainingUses > 0), their RemainingUses will be decremented, consistent with the operation of ConsumeItem.

Request Details

Specify the container and optionally the catalogVersion for the container to open

UnlockContainerInstanceRequest
Request Properties
CatalogVersion String

Specifies the catalog version that should be used to determine container contents. If unspecified, uses catalog associated with the item instance.

CharacterId String

Unique PlayFab assigned ID for a specific character owned by a user

ContainerItemInstanceId (required) String

ItemInstanceId of the container to unlock.

KeyItemInstanceId String

ItemInstanceId of the key that will be consumed by unlocking this container. If the container requires a key, this parameter is required.

POST https://{{TitleID}}.playfabapi.com/Client/UnlockContainerInstance
    Content-Type: application/json
    X-Authentication: <user_session_ticket_value>
{
  "ContainerItemInstanceId": "123456788",
  "KeyItemInstanceId": "123456789"
}
        

Response Details

The items and vc found within the container. These will be added and stacked in the appropriate inventory.

UnlockContainerItemResult
Result Properties
GrantedItems List<ItemInstance>

Items granted to the player as a result of unlocking the container.

UnlockedItemInstanceId String

Unique instance identifier of the container unlocked.

UnlockedWithItemInstanceId String

Unique instance identifier of the key used to unlock the container, if applicable.

VirtualCurrency Dict<String, uint32>

Virtual currency granted to the player as a result of unlocking the container.

Sample Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
  "code": 200,
  "status": "OK",
  "data": {
    "UnlockedItemInstanceId": "0394760938094",
    "GrantedItems": [
      {
        "ItemId": "shield_level_5",
        "ItemInstanceId": "Unique Item ID",
        "ItemClass": "shields",
        "PurchaseDate": "2014-03-07T00:00:00Z",
        "Expiration": "2015-10-01T00:00:00Z",
        "RemainingUses": 10,
        "Annotation": "No Annotation",
        "CatalogVersion": "5",
        "BundleParent": "crate block 1",
        "UnitPrice": 0
      }
    ],
    "VirtualCurrency": {
      "GC": 20
    }
  }
}

Authentication

SessionTicket

Possible Error Codes

Name Code
CharacterNotFound 1135
ContainerNotOwned 1018
InvalidContainerItem 1017
InvalidItemIdInTable 1020
KeyNotOwned 1019