Unaffiliated

Home Documentation & Help
Steamworks Documentation
Steam Inventory Schema

ItemDef Schema Overview

Core Schema

These are the core properties that are understood & interpreted by Steam and are necessary for the correct operation of economy, trading and inventory display. Many of these properties are the same as those returned by the ISteamEconomy/GetAssetClassInfo Web API.

An itemdef must be one of the following types

NameDescription
iteman item type that can be found in a player inventory.
bundlerepresents a collection of ItemDefs, with an associated quantity of each type. When this item is granted, it automatically expands into the set of items configured in the bundle property.
generatorrepresents a random item. Granting this item will randomly select one item type from the bundle property, and create an instance of that type. (For example: think a crate when unlocked one of the possible items is created)
playtimegeneratorthis is a special form of generator that can be granted by the ISteamInventory::TriggerItemDrop call from the application.
tag_generatorspecial item definition that applies tags to item instances (see Steam Inventory Item Tags for more details).
See below for detail on specifying complex item types.

ItemDef Properties

NameDescription
appidThe ID of your application
nameThe English name of your item. You can provide localized versions of the name of your item using the following example as a guide:
name_english: "Hat" name_french: "Chapeau"
See the Localization and Languages documentation for valid language names to use as the suffix.
descriptionThe English description of your item.
You can provide localized versions of the description of your item using the following example as a guide:
description_english: "This is a tall hat" description_french: "Ceci est un chapeau haut de forme"
See the Localization and Languages documentation for valid language names to use as the suffix.
display_typeThe English description of item's "type".
You can provide localized versions of the type of your item using the following example as a guide:
display_type_english: "Weapon" display_type_french: "Arme"
See the Localization and Languages documentation for valid language names to use as the suffix.
itemdefidThe ID of this itemdef. This must be lower than 1,000,000 for non-workshop items.
typeInternal value. ('item' | 'bundle' | 'generator' | 'playtimegenerator' | 'tag_generator')
bundle(see bundle or generator items below)
promo(see promo format below)
drop_start_timeUTC timestamp - prevent promo grants before this time, only applicable when promo = manual (see promo format below)
exchange(see exchange format below)
price(see price format below)
price_categoryA preset price, where we handle the various currency values for you. (see price format below)
background_colorThe color to display in the inventory background as 6 hex digits.
name_colorThe color to display the name in the inventory as 6 hex digits.
icon_urlThe URL to the item's small icon. Recommended size is 200x200.
icon_url_largeThe URL to the item's large image. Recommended size is 2048x2048.
marketablefalse / true . Whether this item can be sold to other users in the Steam Community Market.
tradablefalse / true . Whether this item can be traded to other users using Steam Trading.
tags(see Steam Inventory Item Tags)
tag_generatorsList of tag_generator item definition ids to apply (see Steam Inventory Item Tags)
tag_generator_nameName of the tag category token (see Steam Inventory Item Tags)
tag_generator_valuesList of tag values and the chance that they will be picked (see Steam Inventory Item Tags)
store_tagsString with "tags" delimited by ";" character. These tags will be used to categorize/filter items in the Steam item store for your app.
hiddenfalse / true . If true, the item definition will not be shown to clients. Use this to hide unused, or under-development, itemdefs.
store_hiddenfalse / true . If true, this item will be hidden in the Steam Item Store for your app. By default, any items with a price will be shown in the store.
use_drop_limitfalse / true . If true, then we rely on drop_limit to limit the items grant via ISteamInventory::TriggerItemDrop. (see Playtime Item Drops below)
drop_limitinteger . Limits for a specific user the number of times this item will be dropped via ISteamInventory::TriggerItemDrop. Settings to zero will prevent any future drops of this item. (see Playtime Item Drops below)
drop_intervalinteger . Playtime in minutes before the item can be granted to the user. (see Playtime Item Drops below)
use_drop_windowfalse / true . If true, we will use the "drop_window" for this itemdef. (see Playtime Item Drops below)
drop_windowinteger . Elapsed time in minutes of a cool-down window before we will grant an item. (see Playtime Item Drops below)
drop_max_per_windowinteger . Numbers of grants within the window permitted before Cool-down applies. Default value is 1. (see Playtime Item Drops below)
granted_manuallyfalse / true. If true, will only be granted when AddPromoItem() or AddPromoItems() are called with the explicit item definition id. Otherwise, it may be granted via the GrantPromoItems() call. Defaults to false.

Common Schema

These are additional properties that we have defined that should be followed by any game that needs the given concept. You aren't required to follow the common properties but doing so will make various forms of integration / consistent tools easier in the future.

NameDescription
item_slotWhat use does this item have in the game. Weapon? Hat? Decoration?
item_qualityinteger. 0- junk, 1- common, 2- uncommon, 3-rare, 4-[...]

Extended Schema

You can also define any additional properties that you need that are specific to your game. We require only that you document your extended properties for us so we can prevent conflicts and move appropriate properties into the common schema.

Bundle and Generator item types

Bundle, generator, and playtimegenerator rules are defined with bundle field.

In the case of bundles, we describe the type and quantity of the contained items.

In a generator or playtimegenerator, we describe the types of the possible item to be generated, and the relative weight of each type. Note that the weights do not need to add to 100, though it may be convenient to do so.

The bundle field is expressed as a series of item recipes separated by ";". Each recipe consists of an itemdef ID, optionally followed by an "x" separator and a desired quantity.

If quantity is not supplied explicitly, "1" is used as a default.

Bundle format

bundle_def : item_recipe , { ";" , item_recipe } item_recipe : item_def , [ "x" , quantity ]

Bundle examples

  • Grant one each of itemdef 201, itemdef 202, itemdef 203:
    type: bundle bundle: 201;202;203
  • Grant one instance with itemdef 101 and five instances of itemdef 102:
    type: bundle bundle: 101x1;102x5
  • Random 90% chance of itemdef 501, 9% chance of itemdef 502, 1% chance of item 503:
    type: generator bundle: 501x90;502x9;503x1
  • 90% chance of a common item; 10% chance of a special item.
    itemdefid: 600 name: Common generator type: generator bundle: 601;602;603;604;605 itemdefid: 700 name: Special generator type: generator bundle: 701;702;703;704;705 itemdefid: 800 name: Master generator type: generator bundle: 700x9;600x1

Note that - as in the last example - bundle and generator definitions can be chained. At grant time, any complex item types are expanded repeatedly until only simple itemdefs remain.

Selling Items

To make certain game items available for sale, simply define prices or price categories in the appropriate itemdefs.
See the Steam Item Store documentation for more information on enabling and customizing your store page.

Selling Bundles

Bundled items can be listed for sale in the Item Store. However, the pricing rules are slightly different. To price a bundled item:
  • Specify price information for each item within the bundle.
  • If any of the contained items should not be available for individual sale, set store_hidden
    to "true" for those items.
  • Set the price or price_category field of the bundle to a simple price (such as VLV0).
    This price will not be used in the store, but it is necessary to signal the Item Store that this is a sellable item.
  • Optionally set the purchase_bundle_discount to a percentage discount for the bundle.

Only the total price (the sum of the bundled items, with the optional bundle discount applied) will be shown in the item store. In the case of Workshop items, the relative pricing of the bundled items is used to allocate revenue to the contributors proportionally.

Bundled items will be expanded in the checkout process, so the user will see the list of granted items. The Steam Refund Policy allows refunding the purchase within certain time limits - but all the enclosed items must still be found in the player's inventory, and unmodified.

Do not attempt to sell items of type generator directly in the Item Store.
To sell an item with a random component (a chest), you should define the chest item as a simple item type. Then create a generator item that accepts the chest as input for an exchange recipe.
After purchase, the player can choose to "open" the chest, at which time you can call ISteamInventory::ExchangeItems to execute the generator. The chest purchase will no longer be refundable once the chest has been opened.

Specifying Prices

Item prices can be defined in either of the following fields, or both.
NameDescription
pricedefine a specific price for each currency. Any currencies not defined will be automatically converted at time of purchase.
price_categorydefine one price, which will be presented in every supported currency using a Valve-maintained pricing table.

The price_category field is specified in the special "VLV" currency. VLV100 is equivalent to $0.99 USD, and is converted to all supported currencies using Valve's conversion rates.

The VLV conversion rates are carefully managed to adapt to currency movements over time. We update prices as necessary, while allowing for minor fluctuations to provide customers with stable pricing and a positive user experience.

Price Format

Price: <version>;<pricelist> Version: "1" <pricelist> : <originalprice>(;<price>)* <originalprice>: <currency><integer>(,<currency><integer)* <price>: (<daterange>)<currency><integer>(,<currency><integer)* <currency> 3 letters like "USD" <integer> amount in currency-specific units <daterange>: YYYYMMDDTHHMMSSZ-YYYYMMDDTHHMMSSZ
<daterange> must be exactly 33 characters.

The list of dateranges must be in descending order (future dates first).

Price Examples

  • price_category: 1;VLV100
    Preset price category using the Valve-maintained pricing table.
  • price: 1;USD100
    ($1.00 in US Dollars)
  • price: 1;USD100,EUR080
    ($1.00 in US Dollars or 0.80 in Euro)
  • price: 1;USD100,EUR080;20130606T080000Z-20280607T080000ZUSD50,EUR40
    ($1.00 in US Dollars or 0.80 in Euro except from 6/6/2013 on when the price is reduced to $0.50 / 0.40)
  • price: 1;USD100,EUR080;20130606T080000Z-20130609T080000ZUSD50,EUR40
    ($1.00 in US Dollars or 0.80 in Euro except from 6/6/2013 until 6/9/13 when the price is reduced to $0.50 / 0.40)

Preset Pricing Table

Here are the current possible values you can use to specify a price_category for your item.
NamePrice in USD
VLV25$0.25 USD
VLV50$0.49 USD
VLV75$0.75 USD
VLV100$0.99 USD
VLV150$1.49 USD
VLV200$1.99 USD
VLV250$2.49 USD
VLV300$2.99 USD
VLV350$3.49 USD
VLV400$3.99 USD
VLV450$4.49 USD
VLV500$4.99 USD
VLV550$5.49 USD
VLV600$5.99 USD
VLV650$6.49 USD
VLV700$6.99 USD
VLV750$7.49 USD
VLV800$7.99 USD
VLV850$8.49 USD
VLV900$8.99 USD
VLV950$9.49 USD
VLV1000$9.99 USD
VLV1100$10.99 USD
VLV1200$11.99 USD
VLV1300$12.99 USD
VLV1400$13.99 USD
VLV1500$14.99 USD
VLV1600$15.99 USD
VLV1700$16.99 USD
VLV1800$17.99 USD
VLV1900$18.99 USD
VLV2000$19.99 USD
VLV2500$24.99 USD
VLV3000$29.99 USD
VLV3500$34.99 USD
VLV4000$39.99 USD
VLV4500$44.99 USD
VLV5000$49.99 USD
VLV6000$59.99 USD
VLV7000$69.99 USD
VLV8000$79.99 USD
VLV9000$89.99 USD
VLV10000$99.99 USD

Promo Items

Promotional items can be granted to players based on a few different criteria:

  • Ownership of an appid (including a DLC appid)
  • An achievement
  • Playtime in an appid
  • Manually granted - client needs to call AddPromoItem with the specific item def id.

The promotional item checks are done by Steam - so these items can be requested safely from the client; see ISteamInventory::AddPromoItem. To define a promotional item, set one or more rules for granting the item in the "promo" property of the item definition.

Note that a promotional item may also be a bundle.

Promotional items that are manually granted can also have drop intervals. As an example, using this you could grant a few items each week based on the player completing some task (e.g. in-game quest). To use this feature, set the drop_start_time and drop_interval values in the itemdef.

Promo items are not granted for ownership of a free title (including free weekend, borrowed titles, etc.).

Promo rule Format

<promo>: <rule> { ";" <rule> } <rule>: app_rule / ach_rule / played_rule / manual_rule <app_rule>: "owns:" <appid> <ach_rule>: "ach:" <achievement name> <played_rule>: "played:" <appid>/<minutes played, defaults to 1> <manual>: "manual"

Promo Examples

// simple promo rule definitions: "promo":"owns:440;owns:480" // has played at least 15 minutes on appid 570: "promo":"played:570/15" // consumable item that can be granted once each week: "itemdefid": 404, "type": "item", "name": "Weekly Quest Item", "promo": "manual", "drop_start_time": "20170801T120000Z", "drop_interval": 604800, ...

Drop Start Time

By setting the promo item's drop start time, it will prevents the item for being granted before this time. This allows you to deploy the code which grants it in advance of the start time for the item. The timestamp needs to be specified in the ISO 8601 format in the GMT time zone: YYYYMMDDTHHMMSSZ. For example: 20050515T171151Z.

Exchange Formulas

Exchange formulas are used by the ExchangeItems API and are specified as a set of one or more recipes separated by semicolons.
Each recipe is a set of required ingredients, separated by commas. Each ingredient consists of an itemdefid number and an optional quantity specified after the x character.

When using ExchangeItems, the caller provides a list of items to be exchanged for the target item.
The server will check each recipe, and choose the first recipe that is satisfied by the item list given.

Note that an item with an Exchange formula may also be a bundle.

Exchange Format

<exchange>: <recipe> { ";" <recipe> } <recipe>: <component> { "," <component> } <component>: <itemdefid> [ "x" <quantity> ]

Exchange Example

"exchange":"100,101;102x5;103x3,104x3"

Item Schema

Instances of items that a user has in their inventory follow the following basic schema.

Core Schema

These are the core properties that are understood & interpreted by Steam and are necessary for the correct operation of economy, trading and inventory display. Many of these properties are the same as those returned by the ISteamEconomy/GetAssetClassInfo Web API.

NameDescription
accountidThe ID of the user (64-bit steam ID) that owns the item
itemidUnique ID assigned by steam. 64-bit unsigned integer
itemdefidThe itemdef id as described above
appidThe ID of your application
quantityNot supported in Steam Inventory Service yet
acquireddate when this was purchased / acquired
priceprice paid for it at acquisition (eg USD49)
state'','traded','revoked','removed','refunded','chargedback'
transidtransaction id that created this item. For a traded item it’s the auditid associated with the trade request
origin'purchase','trade','promo','gametime','exchange','support','external','market'
originalitemidfor an item that wasn't granted new, the ID of the original item. If an item has been traded multiple times this will still point to the first instance. Will point to itself if the item is original.
positionWhere is this item in the user's backpack.
tradable_after_timestampDate where the item becomes tradable or sellable on the Market

Playtime Item Drops

The playtime item drops feature allows the steam servers to track and to manage item drops based on the user's playtime. Your game only needs to call the function ISteamInventory::TriggerItemDrop when you believe a grant should occur. You need to create item's of type "playtypegenerator" to perform the drop.
The playtime grant is controlled by your application. There is no support for automatic grants based entirely on the users playtime. In other words, playtime is a condition for granting, while your application is the trigger for the grant evaluation.

The item drop frequency can be controlled at the application level via the Community->Inventory Service->Playtime Item Grants section. There are three controls that will allow the following customization:
(1) How long before a item drop?
(2) How many items drops in a window? And,
(3) How long is the cool-down window before we can grant another item drop?

The same control exists per itemdef. Values set at the item will override any settings at the application for that specific item. This allows each item to have their own drop rate, max-per-window and cool-down window.

Each playtime generator grant will be tracked separately if any of the drop settings are specified ('drop_interval', 'use_drop_window', 'drop_window', "drop_max_per_window' ). In other words, if the itemdef does NOT any drop settings, then it shares drops with all other playtime generators without drop settings and they are all limited by the application's drop interval. Otherwise, if the itemdef does explicitly specify any drop setting, then its drops are granted/tracked separately at the generator level, independent of the application or other itemdef playtime generators.

Playtime ItemDef Grant Example

  1. Allow the user to be granted an item after 30 minutes of playtime. A downside of this setting alone is that it allows
    farming for that item, as every 30 minutes will allow them be eligible for a playtime grant. We strongly suggest adding a drop window setting:
    "drop_interval" : 30
  2. Limit to a single drop per day after 30 minutes of playtime. This rewards your players everyday when they return to play your title.
    "drop_interval" : 30,
    "use_drop_window" : "true",
    "drop_window" : "1440"

  3. Allows the user to gain three items each day by playing for at least 90 minutes. These minutes do not need to be contiguous. This reward longer game play.
    "drop_interval" : 30,
    "use_drop_window" : "true",
    "drop_window" : "1440",
    "drop_max_per_window" : "3"
If a particular itemdef setting is missing then it will default to the setting defined at the application.

Drop Limits

The drop_limit variable allows a maximum playtime grants for a specific generator.
You can use to limit the times an item is generated (for example: Only the first time they beat the game on Legendary difficulty).
Alternatively it can be used to prevent any future drops of a deprecated item if the value is set to zero. We will only acknowledge this setting if the use_drop_limit is assigned to "true".

ItemDef Schema Example:

{ "appid": 480, "items": [ { "itemdefid": 10, "type": "playtimegenerator", "bundle": "100x100;101x50;102x25;103x2;110x20;111x20;120x5;121x3", "name": "Drop Generator", "name_color": "7D6D00", "background_color": "3C352E", "item_slot": "generator", "item_quality": 0, "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", "tradable": false, "marketable": false }, { "itemdefid": 100, "type": "item", "name": "Hat decoration", "description": "Hat decoration description", "price": "1;USD99", "name_color": "7D6D00", "background_color": "3C352E", "item_slot": "decoration", "item_quality": 0, "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", "tradable": true, "marketable": true }, { "itemdefid": 200, "type": "item", "price": "1;VLV100", "name_english": "Red Hat", "name_german": "Roter Hut", "description_english": "Red Hat", "description_german": "Roter Hut", "store_tags": "hat;featured", "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", "tradable": true, "marketable": true } ] }