Amba
Virtual Economy

Player Inventory

Track owned items and quantities per user with grant and consume operations.

The inventory system tracks what items each user owns, including quantities for consumable items.

Client API reference

MethodPathDescription
GET/client/inventoryGet current user's inventory
POST/client/inventory/:id/consumeUse a consumable item

Get inventory

GET /client/inventory
 
{
  "data": [
    { "catalog_item_id": "item_dark_theme", "item_key": "theme_dark", "quantity": 1, "item_type": "durable" },
    { "catalog_item_id": "item_extra_life", "item_key": "extra_life", "quantity": 3, "item_type": "consumable" }
  ]
}

MCP tools

ToolDescription
amba_inventory_grant_itemGrant an item directly to a user (bypasses purchase)
amba_inventory_revoke_itemRevoke an item — the support / correction inverse of grant
amba_users_get_inventoryView a user's inventory

Example: Grant starter items

Agent: "Give all new users a starter pack"

amba_inventory_grant_item({
  project_id: "proj_xxx",
  app_user_id: "user_xxx",
  catalog_item_id: "item_starter_theme",
  quantity: 1
})

Support & moderation: revoking an item

Granting is additive; amba_inventory_revoke_item is the inverse — use it to claw back a wrongly-granted item or fix a quantity. It decrements the held quantity (default 1) and removes the holding entirely when it reaches zero. Revoking more than the user holds returns INSUFFICIENT_QUANTITY; revoking an item they don't hold returns a not-found error. No partial revoke — the request either fully succeeds or fully fails.

Agent: "Tom was double-credited the starter theme — pull one copy back"

amba_inventory_revoke_item({
  project_id: "proj_xxx",
  app_user_id: "user_xxx",
  catalog_item_id: "item_starter_theme",
  quantity: 1
})

Previous

Stores

Next

Referrals

On this page