Documentation

UnlockContainerInstance

Opens a specific container (ContainerItemInstanceId), with a specific key (KeyItemInstanceId, 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.

PlayFabId (required) String

Unique PlayFab assigned ID of the user on whom the operation will be performed.

POST https://{{TitleID}}.playfabapi.com/Server/UnlockContainerInstance
    Content-Type: application/json
    X-SecretKey: <developer_secret_key>
{
  "PlayFabId": "20394883",
  "ContainerItemInstanceId": "123456788",
  "KeyItemInstanceId": "123456789"
}
        

Response Details

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

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

SecretKey

Possible Error Codes

Name Code
ContainerKeyInvalid 1205
ContainerNotOwned 1018
InvalidContainerItem 1017
InvalidItemIdInTable 1020
InvalidItemProperties 1091
KeyNotOwned 1019