ItemDef Schema Overview

Core Schema and Item Types

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:

Name	Description
item	an item type that can be found in a player inventory.
bundle	represents 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.
generator	represents 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: imagine when a crate is unlocked, then one of the possible items is created)
playtimegenerator	this is a special form of generator that can be granted by the ISteamInventory::TriggerItemDrop call from the application.
tag_generator	special 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

Name	Description
appid	The ID of your application
name	The 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.
description	The 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_type	The 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.
itemdefid	The ID of this itemdef. This must be lower than 1,000,000 for non-workshop items.
type	Internal value. ('item' | 'bundle' | 'generator' | 'playtimegenerator' | 'tag_generator')
bundle	(see bundle or generator items below)
promo	(see promo format below)
drop_start_time	UTC 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_category	A preset price, where we handle the various currency values for you. (see price format below)
background_color	The color to display in the inventory background as 6 hex digits.
name_color	The color to display the name in the inventory as 6 hex digits.
icon_url	The URL to the item's small icon. The URL should be publicly accessible because the Steam servers will download and cache. Recommended size is 200x200.
icon_url_large	The URL to the item's large image. The URL should be publicly accessible because the Steam servers will download and cache. Recommended size is 2048x2048.
marketable	false / true . Whether this item can be sold to other users in the Steam Community Market.
tradable	false / true . Whether this item can be traded to other users using Steam Trading.
tags	(see Steam Inventory Item Tags)
tag_generators	List of tag_generator item definition ids to apply (see Steam Inventory Item Tags)
tag_generator_name	Name of the tag category token (see Steam Inventory Item Tags)
tag_generator_values	List of tag values and the chance that they will be picked (see Steam Inventory Item Tags)
store_tags	String with "tags" delimited by ";" character. These tags will be used to categorize/filter items in the Steam item store for your app.
store_images	Image URLs delimited by ";" character. These images will be proxied and used on the detail page of the Steam item store for your app.
game_only	false / true . If true, then items will not be shown in the user's Steam Backpack, including new item notifications. Common uses for this are items that you grant, that are immediately consumed.
hidden	false / true . If true, the item definition will not be shown to clients or purchasable. Use this to hide unused, or under-development, itemdefs.
store_hidden	false / 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_limit	false / true . If true, then we rely on drop_limit to limit the items grant via ISteamInventory::TriggerItemDrop. (see Playtime Item Drops below)
drop_limit	integer . Limits for a specific user the number of times this item will be dropped via ISteamInventory::TriggerItemDrop. Setting to zero will prevent any future drops of this item. (see Playtime Item Drops below)
drop_interval	integer . Playtime in minutes before the item can be granted to the user. (see Playtime Item Drops below)
use_drop_window	false / true . If true, we will use the "drop_window" for this itemdef. (see Playtime Item Drops below)
drop_window	integer . Elapsed time in minutes of a cool-down window before we will grant an item. (see Playtime Item Drops below)
drop_max_per_window	integer . Numbers of grants within the window permitted before Cool-down applies. Default value is 1. (see Playtime Item Drops below)
granted_manually	false / 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.
use_bundle_price	false / true. See selling bundle items below. Defaults to false.
auto_stack	false / true. If true, item grants will automatically be added to a single stack of the given type. Grants will be visible in inventory callbacks as quantity changes. Defaults to false.

Extended Schema

You can also define any additional properties that you need that are specific to your game.

Using Complex Item Definitions

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 (integer) quantity.

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

Bundle format

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: 600x9;700x1

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.

Exchange Formulas

The ExchangeItems API allows you to define item crafting/transformation recipes that can be securely called from the client. Steam servers will check the player inventory and atomically consume the given materials and grant a target item if the requirements are met.

The target item may be a bundle or generator type.

The formula is provided in the exchange field of the target item. The formula is specified as a set of one or more recipes separated by semicolons.

Each recipe is a set of required material items, separated by commas.

Required materials can be given explicitly by itemdefid, or by tag. If quantity is not given, 1 is assumed.

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

Exchanges are flexible - using a key to open a crate, building a fancy item out of component parts, item recycling, and item upgrades can all be achieved with these formulas.

Exchange Format

If not explicitly given, required quantity is 1.

Exchange Example

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 temporary ownership of a free title (Free Weekend, accessed via Family Sharing, etc).

Promo rule Format

Promo Examples

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 UTC time zone: YYYYMMDDTHHMMSSZ. For example: 20050515T171151Z.

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 items of type "playtimegenerator" 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".

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.

Specifying Prices

Item prices can be defined in either of the following fields, but not both.

Name	Description
price	define a specific price for each currency. Any currencies not defined will be automatically converted at time of purchase.
price_category	define 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

<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;20130607T080000Z-20130606T080000ZUSD50,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;20130609T080000Z-20130606T080000ZUSD50,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)

Selling Bundles

Bundled items can be listed for sale in the Item Store. The bundle 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.

Bundle Prices

When pricing a bundle, there are a few additional steps to consider. Steam uses the prices of the individual item within the bundle to determine the bundle price, and to allocate the bundle revenue proportionately. This allocation will determine the value of Workshop contributor payouts. One bundle can easily mix content from different Workshop contributors, or include Workshop content with your own first-party content.

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 to the Item Store that this is a sellable item.
  
• Optionally set the purchase_bundle_discount to a percentage discount for the bundle.

If you prefer, you can specify an exact bundle price in each currency. The bundle price override will ignore any purchase_bundle_discount you specify. However, the individual item prices are still used to proportionately allocate the bundle revenue, so they must be provided.

To override the automatic bundle price:

• Specify your desired price in the price or price_category field of the bundle.
  
• Set the use_bundle_price to true for the bundle item.

Selling Generator items

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.

VLV Preset Pricing Table

Here are the current possible values you can use to specify a price_category for your item.

Name	Price 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

ItemDef Schema Example: