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/
Name | Type | Required | Description |
key | string | ✔ | Steamworks Web API publisher authentication key. |
appid | uint32 | ✔ | The ID of the application associated with the item. |
itemdefid | uint64 | ✔ | List of the itemdefid's to grant. This should be specified as a series of parameters named 'itemdefid[0]', 'itemdefid[1]', etc. |
itempropsjson | string | ✔ | |
steamid | uint64 | ✔ | SteamID of the player to receive the items. |
notify | bool | ✔ | Optional, default 0. Set to 1 to indicate the user is not in-game and should see a Steam notification. |
requestid | uint64 | ✔ | Optional, 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. |
trade_restriction | bool | ✔ | Optional, default 0. Set to 1 to have Steam apply market and trade cooldowns as if this was a purchased item. |
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.
If the user owns your app from a free license and has not played in the last 30 days, AddItem will also fail.
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/
Name | Type | Required | Description |
key | string | ✔ | Steamworks Web API publisher authentication key. |
appid | uint32 | ✔ | |
itemdefid | uint64 | | |
steamid | uint64 | ✔ | |
notify | bool | | Should notify the user that the item was added to their Steam Inventory. |
requestid | uint64 | 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. | |
Adds a promo item to a user's inventory. If called without the itemdefid parameter, checks for and grants available promo items for the given player.
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/
Name | Type | Required | Description |
key | string | ✔ | Steamworks Web API publisher authentication key. |
appid | uint32 | ✔ | |
itemid | uint64 | ✔ | Item ID to be consumed |
quantity | string | ✔ | Amount of the given item stack to be consumed |
steamid | uint64 | ✔ | |
requestid | uint64 | ✔ | 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. |
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::ConsumeItemExchangeItem
POST https://partner.steam-api.com/IInventoryService/ExchangeItem/v1/
Name | Type | Required | Description |
key | string | ✔ | Steamworks Web API publisher authentication key. |
appid | uint32 | ✔ | The ID of the application associated with the item. |
steamid | uint64 | ✔ | SteamID of the player that owns the items. |
materialsitemid | uint64 | ✔ | The 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. |
materialsquantity | uint32 | ✔ | The quantity of the matching item that should be used in this recipe. This array must be the same length as materialsitemid . |
outputitemdefid | uint64 | ✔ | The 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::ExchangeItemsResponse: -
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/
Name | Type | Required | Description |
key | string | ✔ | Steamworks Web API publisher authentication key. |
appid | uint32 | ✔ | The ID of the application associated with the item. |
steamid | uint64 | ✔ | 64-bit Steam ID of the user whose 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/
Name | Type | Required | Description |
key | string | ✔ | Steamworks Web API publisher authentication key. |
appid | uint32 | ✔ | The ID of the application associated with the item. |
modifiedsince | string | ✔ | Use to retrieve just updates to the itemdefs since a given time. Format is yyyymmddThhmmssZ (E.g. 20140808T010203Z). |
itemdefids | uint64 | ✔ | Use to retrieve just specific itemdefs by itemdefid |
workshopids | uint64 | ✔ | Use to retrieve just specific itemdefs by workshopid |
cache_max_age_seconds | uint32 | | Allow 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/
Name | Type | Required | Description |
key | string | ✔ | Steamworks Web API user authentication key. |
ecurrency | int32 | ✔ | |
Get the Inventory Service price sheet
Consolidate
POST https://partner.steam-api.com/IInventoryService/Consolidate/v1/
Name | Type | Required | Description |
key | string | ✔ | Steamworks Web API publisher authentication key. |
appid | uint32 | ✔ | |
steamid | uint64 | ✔ | |
itemdefid | uint64 array | ✔ | |
force | bool | | |
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/
Name | Type | Required | Description |
key | string | ✔ | Steamworks Web API publisher authentication key. |
appid | uint32 | ✔ | |
steamid | uint64 | ✔ | |
itemdefid | uint64[] | ✔ | List of the itemdefid's to query. This should be specified as a series of parameters named 'itemdefid[0]', 'itemdefid[1]', etc. |
force | bool | | |
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!
ModifyItems
POST https://partner.steam-api.com/IInventoryService/ModifyItems/v1/
Name | Type | Required | Description |
key | string | ✔ | Steamworks Web API publisher authentication key. |
appid | uint32 | ✔ | |
input_json | string | ✔ | |
steamid | uint64 | ✔ | The steamid of the user who owns the items. Must be specified in the input_json parameter. |
timestamp | uint32 | ✔ | Unix timestamp of the request. An error will be returned if the items have been modified since this request time. Must be specified in the input_json parameter. |
updates | message | ✔ | The list of items and properties being modified. Must be specified in the input_json parameter. |
Structure of the
updates
property:
Name | Type | Required | Description |
itemid | uint64 | ✔ | The id of the item being modified. |
property_name | string | ✔ | The name of the dynamic property being added/updated/removed. |
property_value_string | string | | The string value of the property to set. |
property_value_bool | bool | | The boolean value of the property to set. |
property_value_int | int64 | | The 64 bit integer value of the property to set. |
property_value_float | string | | The 32 bit float value of the property to set. |
remove_property | bool | | Set to true if the property should be removed. |
Modify the
dynamic properties on items for the given user. This call is rate-limited per user and currently only 100 items can be modified in one call.
Example input_json
:
{
"steamid": "76561197970323416",
"timestamp": 1513274037,
"updates": [
{
"itemid": "1",
"property_name": "fx",
"property_value_string": "blue_flames"
},
{
"itemid": "1",
"property_name": "quality",
"property_value_string": "high"
},
{
"itemid": "1",
"property_name": "color",
"remove_property": true
}
]
}
Calling Example:curl --request POST \
--header 'content-type: multipart/form-data' \
--form appid=30400 \
--form 'input_json={ "steamid" : "76561197970323416", "timestamp" : 1513274037, "updates" : [] }' \
https://api.steampowered.com/IInventoryService/ModifyItems/v1?key=xxxxxxxxxx'
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!