> ## Documentation Index > Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt > Use this file to discover all available pages before exploring further. # Unlock Container Instance > _NOTE: This is a Legacy Economy API, and is in bugfix-only mode. All new Economy features are being developed only for version 2._ 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. ## Error codes This operation may return the following PlayFab errors: | Error | Code | | --- | --- | | ContainerKeyInvalid | 1205 | | ContainerNotOwned | 1018 | | InvalidContainerItem | 1017 | | InvalidItemIdInTable | 1020 | | InvalidItemProperties | 1091 | | KeyNotOwned | 1019 | | ProductDisabledForTitle | 1609 | ## OpenAPI ````yaml post /Server/UnlockContainerInstance openapi: 3.0.0 info: version: '260922' title: PlayFab Server API description: >- Provides functionality to allow external (developer-controlled) servers to interact with user inventories and data in a trusted manner, and to handle matchmaking and client connection orchestration termsOfService: https://playfab.com/terms/ contact: url: https://community.playfab.com/index.html license: name: Apache 2.0 url: https://github.com/PlayFab/API_Specs/blob/master/LICENSE servers: - url: https://{titleId}.playfabapi.com description: PlayFab title endpoint variables: titleId: default: your_title_id description: Your PlayFab title ID (hex). security: [] tags: - name: Account Management description: Account Management APIs - name: Analytics description: Analytics APIs - name: Authentication description: Authentication APIs - name: Character Data description: Character Data APIs - name: Characters description: Characters APIs - name: Content description: Content Service APIs - name: Friend List Management description: Friend List Management APIs - name: Matchmaking description: Matchmaking APIs - name: Platform Specific Methods description: Platform Specific Methods APIs - name: Player Data Management description: Player Data Management APIs - name: Player Item Management description: Player Item Management APIs - name: PlayStream description: PlayStream Management APIs - name: Server-Side Cloud Script description: Server-Side Cloud Script APIs - name: Shared Group Data description: Shared Group Data APIs - name: Title-Wide Data Management description: Title-Wide Data Management APIs paths: /Server/UnlockContainerInstance: post: tags: - Player Item Management summary: Unlock Container Instance description: > _NOTE: This is a Legacy Economy API, and is in bugfix-only mode. All new Economy features are being developed only for version 2._ 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. ## Error codes This operation may return the following PlayFab errors: | Error | Code | | --- | --- | | ContainerKeyInvalid | 1205 | | ContainerNotOwned | 1018 | | InvalidContainerItem | 1017 | | InvalidItemIdInTable | 1020 | | InvalidItemProperties | 1091 | | KeyNotOwned | 1019 | | ProductDisabledForTitle | 1609 | operationId: UnlockContainerInstance requestBody: content: application/json: schema: $ref: '#/components/schemas/UnlockContainerInstanceRequest' description: >- Specify the container and optionally the catalogVersion for the container to open responses: '200': $ref: '#/components/responses/UnlockContainerItemResult' '400': $ref: '#/components/responses/ApiErrorWrapper' security: - SecretKey: [] components: schemas: UnlockContainerInstanceRequest: description: >- Specify the container and optionally the catalogVersion for the container to open type: object properties: CatalogVersion: description: >- Specifies the catalog version that should be used to determine container contents. If unspecified, uses catalog associated with the item instance. type: string CharacterId: description: Unique PlayFab assigned ID for a specific character owned by a user type: string ContainerItemInstanceId: description: ItemInstanceId of the container to unlock. type: string CustomTags: description: >- The optional custom tags associated with the request (e.g. build number, external trace identifiers, etc.). type: object KeyItemInstanceId: description: >- ItemInstanceId of the key that will be consumed by unlocking this container. If the container requires a key, this parameter is required. type: string PlayFabId: description: >- Unique PlayFab assigned ID of the user on whom the operation will be performed. type: string required: - PlayFabId - ContainerItemInstanceId example: PlayFabId: '20394883' ContainerItemInstanceId: '123456788' KeyItemInstanceId: '123456789' UnlockContainerItemResult: description: >- The items and vc found within the container. These will be added and stacked in your inventory as appropriate. type: object properties: GrantedItems: description: Items granted to the player as a result of unlocking the container. type: array items: $ref: '#/components/schemas/ItemInstance' x-isclass: true UnlockedItemInstanceId: description: Unique instance identifier of the container unlocked. type: string UnlockedWithItemInstanceId: description: >- Unique instance identifier of the key used to unlock the container, if applicable. type: string VirtualCurrency: description: >- Virtual currency granted to the player as a result of unlocking the container. type: object x-actualtype: uint32 example: UnlockedItemInstanceId: '0394760938094' GrantedItems: - ItemId: shield_level_5 ItemInstanceId: Unique Item ID ItemClass: shields PurchaseDate: '2014-03-07T00:00:00' Expiration: '2015-10-01T00:00:00' RemainingUses: 10 Annotation: No Annotation CatalogVersion: '5' BundleParent: crate block 1 VirtualCurrency: GC: 20 ApiErrorWrapper: description: The basic wrapper around every failed API response type: object properties: code: description: Numerical HTTP code type: integer status: description: String HTTP code type: string error: description: Playfab error code type: string errorCode: description: Numerical PlayFab error code type: integer errorMessage: description: Description for the PlayFab errorCode type: string errorDetails: description: Detailed description of individual issues with the request object type: object required: - code - errorCode ItemInstance: description: >- A unique instance of an item in a user's inventory. Note, to retrieve additional information for an item such as Tags, Description that are the same across all instances of the item, a call to GetCatalogItems is required. The ItemID of can be matched to a catalog entry, which contains the additional information. Also note that Custom Data is only set when the User's specific instance has updated the CustomData via a call to UpdateUserInventoryItemCustomData. Other fields such as UnitPrice and UnitCurrency are only set when the item was granted via a purchase. type: object properties: Annotation: description: >- Game specific comment associated with this instance when it was added to the user inventory. type: string BundleContents: description: >- Array of unique items that were awarded when this catalog item was purchased. type: array items: type: string BundleParent: description: >- Unique identifier for the parent inventory item, as defined in the catalog, for object which were added from a bundle or container. type: string CatalogVersion: description: >- Catalog version for the inventory item, when this instance was created. type: string CustomData: description: >- A set of custom key-value pairs on the instance of the inventory item, which is not to be confused with the catalog item's custom data. type: object DisplayName: description: CatalogItem.DisplayName at the time this item was purchased. type: string Expiration: description: Timestamp for when this instance will expire. type: string ItemClass: description: Class name for the inventory item, as defined in the catalog. type: string ItemId: description: Unique identifier for the inventory item, as defined in the catalog. type: string ItemInstanceId: description: Unique item identifier for this specific instance of the item. type: string PurchaseDate: description: Timestamp for when this instance was purchased. type: string RemainingUses: description: Total number of remaining uses, if this is a consumable item. type: number x-actualtype: int32 UnitCurrency: description: >- Currency type for the cost of the catalog item. Not available when granting items. type: string UnitPrice: description: >- Cost of the catalog item in the given currency. Not available when granting items. type: number x-actualtype: uint32 UsesIncrementedBy: description: >- The number of uses that were added or removed to this item in this call. type: number x-actualtype: int32 required: - UnitPrice example: ItemId: shield_level_5 ItemInstanceId: '133713371337' ItemClass: shields PurchaseDate: '2017-03-07T00:00:00' Expiration: '2018-10-01T00:00:00' RemainingUses: 10 Annotation: No Annotation CatalogVersion: '5' BundleParent: crate block 1 x-sortKey: ItemInstanceId responses: UnlockContainerItemResult: description: >- The items and vc found within the container. These will be added and stacked in your inventory as appropriate. content: application/json: schema: type: object properties: code: type: integer description: >- The Http status code. If X-ReportErrorAsSuccess header is set to true, this will report the actual http error code. status: type: string description: The Http status code as a string. data: $ref: '#/components/schemas/UnlockContainerItemResult' example: code: 200 status: OK data: UnlockedItemInstanceId: '0394760938094' GrantedItems: - ItemId: shield_level_5 ItemInstanceId: Unique Item ID ItemClass: shields PurchaseDate: '2014-03-07T00:00:00' Expiration: '2015-10-01T00:00:00' RemainingUses: 10 Annotation: No Annotation CatalogVersion: '5' BundleParent: crate block 1 VirtualCurrency: GC: 20 ApiErrorWrapper: description: This is the outer wrapper for all responses with errors content: application/json: schema: $ref: '#/components/schemas/ApiErrorWrapper' securitySchemes: SecretKey: type: apiKey in: header name: X-SecretKey description: >- This API requires a title secret key, available to title admins, from PlayFab Game Manager. ```` ## Related topics - [Unlock Container Instance](/api-reference/player-item-management/unlock-container-instance.md) - [Using Player inventory](/services/playfab/player-progression/player-data/player-inventory.md) - [Profile Writes Meter API Description](/services/playfab/pricing/meters/profile-writes.md) - [Unlock Container Item](/services/playfab/api-references/rest/client/player-item-management/unlock-container-item.md) - [Get Catalog Items](/services/playfab/api-references/rest/admin/title-wide-data-management/get-catalog-items.md)