Note: This feature is currently in closed beta, and it will not function unless your game is included in the beta program. If you feel you are a good test candidate for this feature then please let us know.

Microtransaction/Items Web Service API

The Kongregate Items API allows you to query for item-related information as well as use limited-use items in a player's inventory. This can be combined with the client side API to enable purchasing items.

Make sure you've read the Kreds Primer for an overview of how microtransactions work on Kongregate.

Requesting a list of available items

This HTTP endpoint allows you to request a list of items available to your game.

GET url: http://www.kongregate.com/api/items.json
required params:
  api_key: The api key assigned to your game

response fields:
  success: true/false depending on if the request was successful
  error: error code integer, if any
  error_description: error code description string, if any

only if successful:
  items: An array of item objects-
    id: Unique integer id for the item
    identifier: String identifier for the item, given by the developer
    name: Name of the item
    description: Description of the item
    price: An integer containing the price of the item in kreds
    tags: An array of strings containing the tags for the item

Example: Request all items

GET http://www.kongregate.com/api/items.json?api_key=MyApiKey

{success:true, 
 items:[
  {id:1,identifier:"sharp-sword",name:"Sharp Sword",description:"A sharp sword",price:10,tags:["sword","awesome"]},
  {id:2,identifier:"dull-sword",name:"Dull Sword",description:"A dull sword",price:1,tags:["sword","awesome"]},
  {id:3,identifier:"axe",name:"Axe",description:"An Axe",price:10,tags:["axe"]}
 ]}

Requesting a user's inventory

This HTTP endpoint allows you to request the list of items that belong to a user. These are referred to as item instances. Item instances will only be returned by this method if they have remaining uses, or are unlimited-use items. This should be done after receiving a callback or successful transaction event, as well as each time the game loads in order to check for un-credited items in the inventory.

GET url: http://www.kongregate.com/api/user_items.json
required params:
  api_key: The api key assigned to your game
  user_id: The user_id of the user to request items for

response fields:
  success: true/false depending on if the request was successful
  error: error code integer, if any
  error_description: error code description string, if any

only if successful:
  items: An array of item instance objects-
    id: Unique integer id for the owned item instance
    identifier: String identifier for the item
    name: Name of the item
    description: Description of the item
    remaining_uses: The number of remaining uses for this item, or null for unlimited
    data: The optional string of metadata you attached to the instance at checkout time

Example: Request all items for a user

GET http://www.kongregate.com/api/user_items.json?api_key=MyApiKey&user_id=765

{success:true, 
 items:[
  {id:100,identifier:"sharp-sword",name:"Sharp Sword",description:"A sharp sword",remaining_uses:null,data:null},
  {id:101,identifier:"potion",name:"Potion",description:"A Healing Poition",remaining_uses:10,data:null},
 ]}

Using an item

This HTTP endpoint allows you to use a limited-use item belonging to a user. You must pass in the id of the item instance to use. This id can be obtained from the user's inventory. It is important to note that this is NOT the same as the item id which is returned from the items action. Calling this action on an unlimited use item will return failure, since that operation is not supported.

POST url: http://www.kongregate.com/api/use_item.json
required params:
  api_key: The api key assigned to your game
  game_auth_token: The game_auth_token for the user
  user_id: The user id of the user
  id: The id (from the user's inventory) of the item instance to use

response fields:
  success: true/false depending on if the request was successful
  error: error code integer, if any
  error_description: error code description string, if any

only if successful:
  remaining_uses: The new amount of remaining uses for the item instance.
  usage_record_id: The unique id of the usage record for this transaction.

Example: Use a limited-use item

POST http://www.kongregate.com/api/use_item.json
 POST data:
  api_key=MyApiKey
  game_auth_token=GameAuthToken
  user_id=765
  id=101

{success:true, remaining_uses:9, usage_record_id:7653}