Unaffiliated

Home Documentation & Help
Steamworks Documentation
IInventoryService Interface
This is the interface used to access the Steam Inventory Service.

NOTE: This is a Service interface, methods in this interface should be called with the input_json parameter.

For more info on how to use the Steamworks Web API please see the Web API Overview.

AddItem

POST https://partner.steam-api.com/IInventoryService/AddItem/v1/
NameTypeRequiredDescription
keystringSteamworks Web API publisher authentication key.
appiduint32The ID of the application associated with the item.
itemdefiduint64List of the itemdefid's to grant. This should be specified as a series of parameter named 'itemdefid[0]', 'itemdefid[1]', etc.
itempropsjsonstring
steamiduint64SteamID of the player to receive the items.
notifyboolOptional, default 0. Set to 1 to indicate the user is not in-game and should see a Steam notification.
requestiduint64Optional, default 0. Clients may provide a unique identifier for a request to perform at most once execution. When a requestid is resubmitted, it will not cause the work to be performed again; the response message will be the current state of items affected by the original successful execution.

AddItem is used to add new items directly in a user's inventory. For each itemdef, an instance of that type is created and added to the target account.

Items of type 'bundle' or 'generator' are unpacked at the time they are added. The response message provides information about the item or items that were actually inserted in the inventory.

This call will fail if the itemdef is not defined or cannot be unpacked; or if the target player does not have permission for the given appid.

Player notification of a new item, if any, is best handled by the game client. Calls to AddItem that occur when the player is not in-game may optionally set notify=1 to notify the player via Steam. This may engage any of the player-notification mechanisms in Steam, including an overlay popup.

The optional requestid parameter allows a client to make an idempotent call. If the client is unsure whether a request completed successfully on the server, it can replay the request, reusing the original request ID.
If the request is replayed, the response will include current state for the items that were affected by the original request, without making new changes.

If the original request fails on the server, replaying the same request ID will re-attempt the work rather than reporting the prior error result.

NOTE: This call requires a publisher API key to use this method. As such this API MUST be called from a secure server, and can never be used directly by clients!

Response:
  • response
    • success - True if the method was successful. If the asset server is returning false, it should set error to a string that explains why.
    • error - a string describing why this call failed. This message will be recorded in the error log, which is available under the Economy tab on the Steamworks site.
    • item_json - an array of the item details of the newly created items. This is returned as encoded JSON containing the actual item properties.
    • replayed - if true, indicates that the given requestid was processed earlier, and the response is based on the original execution. This will not be included if requestid is not specified.

Example Response:
{ "response": { "item_json": "[{ \"accountid\":\"148618792083651397\",\"itemid\":\"17209346500926339\",\"Timestamp\":\"\",\"originalitemid\":\"17209346500926339\",\"itemdefid\":\"120\",\"appid\":480,\"position\":0,\"quantity\":1,\"transid\":\"\",\"state\":\"\",\"origin\":\"external\",\"price\":\"\",\"acquired\":\"20140912T195537Z\"}]" } }

Calling Example:
curl -X POST -H "Content-Type: application/x-www-form-urlencoded" \ -d appid=480 \ -d steamid=292733980074050545 \ -d itemdefid[0]=4111 \ -d itemdefid[1]=4112 \ "http://api.steampowered.com/IInventoryService/AddItem/v1?key=xxxxxx"

AddPromoItem

POST https://partner.steam-api.com/IInventoryService/AddPromoItem/v1/
NameTypeRequiredDescription
keystringSteamworks Web API publisher authentication key.
appiduint32
itemdefiduint64
itempropsjsonstring
steamiduint64
notifyboolShould notify the user that the item was added to their Steam Inventory.
requestiduint64

Adds a promo item to a user's inventory

NOTE: This call requires a publisher API key to use this method. As such this API MUST be called from a secure server, and can never be used directly by clients!

ConsumeItem

POST https://partner.steam-api.com/IInventoryService/ConsumeItem/v1/

NameTypeRequiredDescription
keystringSteamworks Web API publisher authentication key.
appiduint32
itemiduint64Item ID to be consumed
quantitystringAmount of the given item stack to be consumed
steamiduint64
requestiduint64

Marks an item as wholly or partially consumed. This action cannot be reversed.

NOTE: This call requires a publisher API key to use this method. As such this API MUST be called from a secure server, and can never be used directly by clients!

A client SDK version of this call is also available: ISteamInventory::ConsumeItem

ExchangeItem

POST https://partner.steam-api.com/IInventoryService/ExchangeItem/v1/
NameTypeRequiredDescription
keystringSteamworks Web API publisher authentication key.
appiduint32The ID of the application associated with the item.
steamiduint64SteamID of the player that owns the items.
materialsitemiduint64The unique ID an item in the player's inventory to be converted to the target item type. This should be provided as materialsitemid[0], materialsitemid[1], etc.
materialsquantityuint32The quantity of the matching item that should be used in this recipe. This array must be the same length as materialsitemid.
outputitemdefiduint64The ItemDef of the item to be created.

ExchangeItem is used for crafting - converting items using a predefined recipe. A successful exchange destroys the set of items required by the crafting recipe, and adds a new instance of the target itemdef to the player's inventory.

The target item definition must have one or more crafting recipes declared in the exchange attribute. Recipes declare the number and type of items required to create the target item. If the set of items provided in the ExchangeItems call does not satisfy any recipe, the call fails and no changes are made to the inventory.

See the Inventory Service Schema documentation for more detail on crafting recipes.

The crafting operation will take trade and market restrictions into account; the created item will have the latest trade restriction of any item used to create it.

If successful, this call returns an encoded JSON blob that lists the items that were changed by this call - the consumed items and the newly created one.
NOTE: Never distribute your Steam API key with your game. This API must be called from a secure server, and cannot be used directly by clients.

A client SDK version of this call is also available: ISteamInventory::ExchangeItems


Response:
  • response
    • item_json - details of all items affected by the exchange. This is returned as a string which contains encoded JSON of the actual item properties. Returns an empty array for unsuccessful exchanges.

Example Response:
{ "response": { "item_json": "[{ \"accountid\":\"292733980074050545\",\"itemid\":\"1503713096879725\",\"itemdefid\":\"4111\",\"state\":\"removed\" ... } }

Calling Example:
curl --request POST \ --header 'content-type: multipart/form-data' \ --form appid=30400 \ --form 'materialsitemid[0]=1510699974025744' \ --form 'materialsitemid[1]=1510699974025745' \ --form 'materialsitemid[2]=1510699974025746' \ --form 'materialsquantity[0]=1' \ --form 'materialsquantity[1]=1' \ --form 'materialsquantity[2]=5' \ --form steamid=292733980074050545 \ --form outputitemdefid=4111 \ https://api.steampowered.com/IInventoryService/ExchangeItem/v1?key=xxxxxxxxxx'

GetInventory

GET https://partner.steam-api.com/IInventoryService/GetInventory/v1/
NameTypeRequiredDescription
keystringSteamworks Web API publisher authentication key.
appiduint32The ID of the application associated with the item.
steamiduint6464-bit Steam ID of the user whos inventory you are requesting.

GetInventory is used to retrieve a user's inventory.

NOTE: This call requires a publisher API key to use this method. As such this API MUST be called from a secure server, and can never be used directly by clients!

Response:
  • response
    • success - True if the method was successful. If the asset server is returning false, it should set error to a string that explains why.
    • error - a string describing why this call failed. This message will be recorded in the error log, which is available under the Economy tab on the Steamworks site.
    • item_json - an array of the item details of the inventory. Each is a string which contains encoded JSON of the actual item properties.

For detailed description on the output values, refer to the Core Schema documentation.

Example Response:
{ "response": { "item_json": "[{ \"accountid\":\"xxxxx\",\"itemid\":\"17212166272724458\",\"Timestamp\":\"2014-10-13T22:41:00.4928464Z\",\"originalitemid\":\"17212166272724458\",\"itemdefid\":\"120\",\"appid\":480,\"position\":0,\"quantity\":1,\"transid\":\"\",\"state\":\"\",\"origin\":\"external\",\"price\":\"\",\"acquired\":\"20141013T224100Z\"}, { \"accountid\":\"xxxxx\",\"itemid\":\"17212166272732706\",\"Timestamp\":\"2014-10-13T22:42:50.1328464Z\",\"originalitemid\":\"17212166272732706\",\"itemdefid\":\"121\",\"appid\":480,\"position\":0,\"quantity\":1,\"transid\":\"\",\"state\":\"\",\"origin\":\"external\",\"price\":\"\",\"acquired\":\"20141013T224250Z\"} ]" }}

Calling Example:
$fields = array( 'appid' > '480', 'itemlist[0]' > '120', 'itemorigin' > '', 'steamid' > 'xxxxx', 'key' > 'xxxx' ); var_dump($fields); $ch = curl_init(); curl_setopt( $ch, CURLOPT_URL, $host.'/IInventoryService/GetInventory/v1?appid=480&steamid=xxxxx&key=yyyyyy' ); curl_setopt( $ch, CURLOPT_RETURNTRANSFER, 1 ); $data = curl_exec( $ch ); var_dump($data);

GetItemDefs

GET https://partner.steam-api.com/IInventoryService/GetItemDefs/v1/
NameTypeRequiredDescription
keystringSteamworks Web API publisher authentication key.
appiduint32The ID of the application associated with the item.
modifiedsincestringUse to retrieve just updates to the itemdefs since a given time. Format is yyyymmddThhmmssZ (E.g. 20140808T010203Z).
itemdefidsuint64Use to retrieve just specific itemdefs by itemdefid
workshopidsuint64Use to retrieve just specific itemdefs by workshopid
cache_max_age_secondsuint32Allow stale data to be returned for the specified number of seconds.

GetItemDefs is used to retrieve the itemdefs for a given application.

NOTE: This call requires a publisher API key to use this method. As such this API MUST be called from a secure server, and can never be used directly by clients!

Response:
  • response
    • success - True if the method was successful. If the asset server is returning false, it should set error to a string that explains why.
    • error - a string describing why this call failed. This message will be recorded in the error log, which is available under the Economy tab on the Steamworks site.
    • itemdef_json - an array of the item details of the newly created item. Each is a string which contains encoded JSON of the actual item properties.

Example Response:
{ "response": { "itemdef_json":"[ { \"appid\":\"480\",\"itemdefid\":\"10\",\"Timestamp\":\"2014-09-12T01:29:10.4628321Z\",\"modified\":\"20140808T010203Z\",\"type\":\"generator\",\"name\":\"Drop Generator/",/"bundle/":/"100x100;101x50;102x25;103x2;110x20;111x20;120x5;121x3/",/"price/":/"/",/"quantity/":0,/"description/":/"/",/"background_color/":/"3C352E/",/"icon_url/":/"http://cdn.beta.steampowered.com/apps/440/icons/c_fireaxe_pyro_xmas_large.fa878752e1aa09a721a03042a234063b6c929278.png/",/"icon_url_large/":/"http://cdn.beta.steampowered.com/apps/440/icons/c_fireaxe_pyro_xmas_large.fa878752e1aa09a721a03042a234063b6c929278.png/",/"market_name/":/"Drop Generator\",\"market_hash_name\":\"Drop Generator\",\"name_color\":\"7D6D00\",\"workshopid\":\"0\",\"flags\":1,\"game_type\":\"generator\",\"itemslot\":\"generator\"}, { \"appid\":\"480\",\"itemdefid\":\"100\",\"Timestamp\":\"2014-09-12T01:28:44.4816369Z\",\"modified\":\"20140808T010203Z\",\"type\":\"item\",\"name\":\"Plus ship decoration/",/"bundle/":/"/",/"price/":/"/",/"quantity/":0,/"description/":/"/",/"background_color/":/"3C352E/",/"icon_url/":/"http://cdn.beta.steampowered.com/apps/440/icons/c_fireaxe_pyro_xmas_large.fa878752e1aa09a721a03042a234063b6c929278.png/",/"icon_url_large/":/"http://cdn.beta.steampowered.com/apps/440/icons/c_fireaxe_pyro_xmas_large.fa878752e1aa09a721a03042a234063b6c929278.png/",/"market_name/":/"Plus ship decoration\",\"market_hash_name\":\"Plus ship decoration\",\"name_color\":\"7D6D00\",\"workshopid\":\"0\",\"flags\":1,\"game_type\":\"decoration\",\"itemslot\":\"decoration\"}, { \"appid\":\"480\",\"itemdefid\":\"101\",\"Timestamp\":\"2014-09-12T01:29:25.5198429Z\",\"modified\":\"20140808T010203Z\",\"type\":\"item\",\"name\":\"Star ship decoration/",/"bundle/":/"/",/"price/":/"/",/"quantity/":0,/"description/":/"/",/"background_color/":/"3C352E/",/"icon_url/":/"http://cdn.beta.steampowered.com/apps/440/icons/c_fireaxe_pyro_xmas_large.fa878752e1aa09a721a03042a234063b6c929278.png/",/"icon_url_large/":/"http://cdn.beta.steampowered.com/apps/440/icons/c_fireaxe_pyro_xmas_large.fa878752e1aa09a721a03042a234063b6c929278.png/",/"market_name/":/"Star ship decoration\",\"market_hash_name\":\"Star ship decoration\",\"name_color\":\"7D6D00\",\"workshopid\":\"0\",\"flags\":1,\"game_type\":\"decoration\",\"itemslot\":\"decoration\"}, { \"appid\":\"480\",\"itemdefid\":\"102\",\"Timestamp\":\"2014-09-12T01:29:33.6544695Z\",\"modified\":\"20140808T010203Z\",\"type\":\"item\",\"name\":\"Stripe ship decoration/",/"bundle/":/"/",/"price/":/"/",/"quantity/":0,/"description/":/"/",/"background_color/":/"3C352E/",/"icon_url/":/"http://cdn.beta.steampowered.com/apps/440/icons/c_fireaxe_pyro_xmas_large.fa878752e1aa09a721a03042a234063b6c929278.png/",/"icon_url_large/":/"http://cdn.beta.steampowered.com/apps/440/icons/c_fireaxe_pyro_xmas_large.fa878752e1aa09a721a03042a234063b6c929278.png/",/"market_name/":/"Stripe ship decoration\",\"market_hash_name\":\"Stripe ship decoration\",\"name_color\":\"7D6D00\",\"workshopid\":\"0\",\"flags\":1,\"game_type\":\"decoration\",\"itemslot\":\"decoration\"}, { \"appid\":\"480\",\"itemdefid\":\"103\",\"Timestamp\":\"2014-09-12T01:29:39.5676519Z\",\"modified\":\"20140808T010203Z\",\"type\":\"item\",\"name\":\"Hat ship decoration/",/"bundle/":/"/",/"price/":/"1;USD99/",/"quantity/":0,/"description/":/"/",/"background_color/":/"3C352E/",/"icon_url/":/"http://cdn.beta.steampowered.com/apps/440/icons/c_fireaxe_pyro_xmas_large.fa878752e1aa09a721a03042a234063b6c929278.png/",/"icon_url_large/":/"http://cdn.beta.steampowered.com/apps/440/icons/c_fireaxe_pyro_xmas_large.fa878752e1aa09a721a03042a234063b6c929278.png/",/"market_name/":/"Hat ship decoration\",\"market_hash_name\":\"Hat ship decoration\",\"name_color\":\"7D6D00\",\"workshopid\":\"0\",\"flags\":1,\"game_type\":\"decoration\",\"itemslot\":\"decoration\"}, { \"appid\":\"480\",\"itemdefid\":\"110\",\"Timestamp\":\"2014-09-12T01:29:44.0715525Z\",\"modified\":\"20140808T010203Z\",\"type\":\"item\",\"name\":\"Doublefire gun/",/"bundle/":/"/",/"price/":/"/",/"quantity/":0,/"description/":/"/",/"background_color/":/"3C352E/",/"icon_url/":/"http://cdn.beta.steampowered.com/apps/440/icons/c_fireaxe_pyro_xmas_large.fa878752e1aa09a721a03042a234063b6c929278.png/",/"icon_url_large/":/"http://cdn.beta.steampowered.com/apps/440/icons/c_fireaxe_pyro_xmas_large.fa878752e1aa09a721a03042a234063b6c929278.png/",/"market_name/":/"Doublefire gun\",\"market_hash_name\":\"Doublefire gun\",\"name_color\":\"7D6D00\",\"workshopid\":\"0\",\"flags\":1,\"game_type\":\"weapon\",\"itemslot\":\"weapon\"}, { \"appid\":\"480\",\"itemdefid\":\"111\",\"Timestamp\":\"2014-09-12T01:29:48.9635307Z\",\"modified\":\"20140808T010203Z\",\"type\":\"item\",\"name\":\"Fastfire gun/",/"bundle/":/"/",/"price/":/"/",/"quantity/":0,/"description/":/"/",/"background_color/":/"3C352E/",/"icon_url/":/"http://cdn.beta.steampowered.com/apps/440/icons/c_fireaxe_pyro_xmas_large.fa878752e1aa09a721a03042a234063b6c929278.png/",/"icon_url_large/":/"http://cdn.beta.steampowered.com/apps/440/icons/c_fireaxe_pyro_xmas_large.fa878752e1aa09a721a03042a234063b6c929278.png/",/"market_name/":/"Fastfire gun\",\"market_hash_name\":\"Fastfire gun\",\"name_color\":\"7D6D00\",\"workshopid\":\"0\",\"flags\":1,\"game_type\":\"weapon\",\"itemslot\":\"weapon\"}, { \"appid\":\"480\",\"itemdefid\":\"120\",\"Timestamp\":\"2014-09-12T01:29:52.9633305Z\",\"modified\":\"20140808T010203Z\",\"type\":\"item\",\"name\":\"Cloaking field/",/"bundle/":/"/",/"price/":/"/",/"quantity/":0,/"description/":/"/",/"background_color/":/"3C352E/",/"icon_url/":/"http://cdn.beta.steampowered.com/apps/440/icons/c_fireaxe_pyro_xmas_large.fa878752e1aa09a721a03042a234063b6c929278.png/",/"icon_url_large/":/"http://cdn.beta.steampowered.com/apps/440/icons/c_fireaxe_pyro_xmas_large.fa878752e1aa09a721a03042a234063b6c929278.png/",/"market_name/":/"Cloaking field\",\"market_hash_name\":\"Cloaking field\",\"name_color\":\"7D6D00\",\"workshopid\":\"0\",\"flags\":1,\"game_type\":\"power\",\"itemslot\":\"power\"}, { \"appid\":\"480\",\"itemdefid\":\"121\",\"Timestamp\":\"2014-09-12T01:30:00.0237423Z\",\"modified\":\"20140808T010203Z\",\"type\":\"item\",\"name\":\"Shield generator/",/"bundle/":/"/",/"price/":/"/",/"quantity/":0,/"description/":/"/",/"background_color/":/"3C352E/",/"icon_url/":/"http://cdn.beta.steampowered.com/apps/440/icons/c_fireaxe_pyro_xmas_large.fa878752e1aa09a721a03042a234063b6c929278.png/",/"icon_url_large/":/"http://cdn.beta.steampowered.com/apps/440/icons/c_fireaxe_pyro_xmas_large.fa878752e1aa09a721a03042a234063b6c929278.png/",/"market_name/":/"Shield generator\",\"market_hash_name\":\"Shield generator\",\"name_color\":\"7D6D00\",\"workshopid\":\"0\",\"flags\":1,\"game_type\":\"power\",\"itemslot\":\"power\"} ]" } }

Calling Example:
$ch = curl_init(); curl_setopt( $ch, CURLOPT_URL, 'https://api.steampowered.com/IInventoryService/GetItemDefs/v1?appid=480&modifiedsince=&itemdefids=&workshopids=&steamid=xxxx&key=xxxxx' ); curl_setopt( $ch, CURLOPT_RETURNTRANSFER, 1 ); $data = curl_exec( $ch ); echo $data . '<br>'; $output = json_decode( $data ); $itemdef = json_decode( $output->response->itemdef_json ); var_dump( $itemdef );

GetPriceSheet

GET https://api.steampowered.com/IInventoryService/GetPriceSheet/v1/
NameTypeRequiredDescription
keystringSteamworks Web API user authentication key.
ecurrencyint32

Get the Inventory Service price sheet

Consolidate

POST https://partner.steam-api.com/IInventoryService/Consolidate/v1/
NameTypeRequiredDescription
keystringSteamworks Web API publisher authentication key.
appiduint32
steamiduint64
itemdefiduint64 array
forcebool

Consolidate items of the given type within an user's inventory.

Whenever items are combined into a stack, the resulting stack takes the market and trade restriction values of the most-restricted item. The Consolidate action ignores any item with an active market or trade restriction, unless 'force' is set to true.

NOTE: This call requires a publisher API key to use this method. As such this API MUST be called from a secure server, and can never be used directly by clients!

GetQuantity

GET https://partner.steam-api.com/IInventoryService/GetQuantity/v1/
NameTypeRequiredDescription
keystringSteamworks Web API publisher authentication key.
appiduint32
steamiduint64
itemdefiduint64
forcebool

Get the total number of available items of the given type

NOTE: This call requires a publisher API key to use this method. As such this API MUST be called from a secure server, and can never be used directly by clients!