5 min read
qb-inventory events, hooks and exports
Use server exports to modify inventories, hooks to examine or reject supported operations before they occur, and listeners to observe operations that completed. Client events mainly drive the inventory UI. There is no public network event for every inventory export.
This page is checked against
qb-inventory commit dc3d07f
(September 11, 2026), including
server/functions.lua,
server/hooks.lua,
server/main.lua
and client/main.lua.
This is a source review, not an in-game test. Check the revision installed on your server.
Conceptual diagram; verify the behavior against your installed resource version.
Choose the right API
| Task | Interface | Side |
|---|---|---|
| Add or remove items | exports['qb-inventory']:AddItem / RemoveItem | Server |
| Check item ownership or capacity | HasItem / CanAddItem exports | Server |
| Open a trusted stash | exports['qb-inventory']:OpenInventory | Server |
| Reject a supported operation | exports['qb-inventory']:AddHook | Server |
| Observe a completed operation | exports['qb-inventory']:AddListener | Server |
| Check an item for local UI | exports['qb-inventory']:HasItem | Client |
| Show an item-box notification | qb-inventory:client:ItemBox | Client |
For installation, storage, shops, and other exports, use the qb-inventory installation guide.
Hooks and listeners (server)
The current inventory registers eight case-sensitive hook/listener types:
| Type | Operation |
|---|---|
ItemMoved | Move, give, stack, split, or swap items |
ItemDropped | Drop an item into the world |
ItemUsed | Use an inventory item |
ItemBought | Buy a shop item |
ItemAdded | Add an item through a supported external path |
ItemRemoved | Remove an item through a supported external path |
InventoryOpened | Open an inventory |
ShopOpened | Open a shop |
Hooks run before an operation and can return false to cancel it. Listeners run after
an operation and their return values are ignored. Register both through server exports, not
through RegisterNetEvent. Registration returns an index, or nil on failure.
Log completed item additions
Put this in your own resource's server.lua. Start qb-inventory before your resource.
local listenerId = exports['qb-inventory']:AddListener('ItemAdded', function(itemType, data)
-- itemType is a category (such as 'item' or 'weapon'), not an item name.
if data.item and data.item.name == 'water_bottle' then
print(('Added %d water bottles to %s'):format(data.amount, tostring(data.toId)))
end
end)
AddEventHandler('onResourceStop', function(resourceName)
if resourceName == GetCurrentResourceName() and listenerId then
exports['qb-inventory']:RemoveListener('ItemAdded', listenerId)
end
end)An ItemAdded payload has toId, toType, toInventory, toSlot, item,
amount, reason, and resource. amount is the quantity in this operation,
not the resulting slot total. Hook inventory snapshots are pre-operation; listener
snapshots are post-operation.
Do not use ItemAdded/ItemRemoved as a universal move audit. The inventory has a separate
ItemMoved event for gives, stacks, splits, swaps and moves.
Block an unauthorized inventory open
This hook checks an inventory identifier that your server registered itself. It does not replace the authorization checks in your own server handlers.
local hookId = exports['qb-inventory']:AddHook('InventoryOpened', function(inventoryType, data)
if inventoryType ~= 'inventory' or data.inventoryId ~= 'police-evidence' then
return
end
local player = exports['qb-core']:GetPlayer(data.source)
if not player or not player.PlayerData.job or player.PlayerData.job.name ~= 'police' then
return false
end
end)
AddEventHandler('onResourceStop', function(resourceName)
if resourceName == GetCurrentResourceName() and hookId then
exports['qb-inventory']:RemoveHook('InventoryOpened', hookId)
end
end)Always validate player identity, access rights, proximity and server-owned inventory IDs before opening a protected inventory. Do not trust client-selected stash IDs.
Signatures and payloads
| Export | Usage |
|---|---|
AddHook(type, callback) | Register a before-operation hook; returns index or nil |
RemoveHook(type, index) | Unregister a hook |
AddListener(type, callback) | Register an after-operation listener; returns index or nil |
RemoveListener(type, index) | Unregister a listener |
ItemMovedcallback:function(moveKind, data)wheremoveKindisgiven,stacked,split,swapped, ormoved. The payload includesfromId,fromType,fromInventory,toId,toType,toInventory,fromSlot,toSlotandamount.ItemAddedcallback:function(itemType, data). This is the one hook that can also return a table to replaceitem.infobefore insertion.ItemRemovedcallback:function(itemType, data), withfromId,fromType,fromInventory,fromSlot,item,amount,reason,resource.ItemUsedcallback:function(itemType, data), withsource,sourceInventoryanditem.InventoryOpenedcallback:function(inventoryType, data), withsource,sourceInventory,inventoryIdandinventory.ShopOpenedcallback:function(shopType, data), withsource,sourceInventoryandshop.
For ItemDropped and ItemBought payloads, see the
project-maintained hooks and listeners reference.
Server exports: add, remove and open
The real server API is exported from server/functions.lua. An AddItem call does not
emit a qb-inventory:server:AddItem event you can subscribe to.
-- server.lua; call this only after your server has verified reward eligibility.
local function grantWaterReward(source)
local canAdd = exports['qb-inventory']:CanAddItem(source, 'water_bottle', 1)
if not canAdd then return false end
return exports['qb-inventory']:AddItem(
source, 'water_bottle', 1, false, false, 'my-resource:reward'
)
endUse exports['qb-inventory']:RemoveItem to remove items. Other current server exports
include GetItemByName, GetItemsByName, HasItem, GetItemCount,
CreateInventory, OpenInventory, CreateShop and OpenShop.
Capacity checks are not reward authorization; never let a client choose item names,
quantities, prices or eligible player IDs.
Real network events (mostly internal)
These events exist in the pinned source but are primarily UI transport, not a stable public integration API:
| Event | Side | Role |
|---|---|---|
qb-inventory:server:closeInventory | Server | Inventory close bookkeeping |
qb-inventory:server:useItem | Server | Inventory item-use transport |
qb-inventory:server:SetInventoryData | Server | Inventory slot-move transport |
qb-inventory:server:openDrop | Server | Inventory drop transport |
qb-inventory:client:openInventory | Client | Open UI |
qb-inventory:client:updateInventory | Client | Refresh UI (case-sensitive) |
qb-inventory:client:ItemBox | Client | Visual notification |
qb-inventory:client:closeInv | Client | Close UI |
qb-inventory:server:giveItem is a QBCore callback, not a net-event handler.
The pinned resource does not expose public events named
qb-inventory:server:OpenInventory, qb-inventory:server:AddItem,
qb-inventory:server:RemoveItem, qb-inventory:server:GiveItem,
qb-inventory:server:TradeItems, or qb-inventory:client:UseItem.
Do not create additional RegisterNetEvent handlers under qb-inventory's own names.
For custom usable-item behavior, use the documented server-side QBCore usable-item API instead of inventing a client usage event.
The current inventory client exports HasItem. OpenInventory and GetItemCount
are server exports in the pinned revision, not client exports.
Migrating from qs-inventory
qs-inventory is a separate inventory product, not a predecessor with guaranteed compatible
events or SQL. Do not migrate by changing the export prefix alone. Back up your data, compare
the exact installed API signatures, and verify reconnects, usable items, stashes, shops and
stored metadata before cutting over.
Related guides
Found an issue in this guide?
Send the page URL, the affected example, and a source or reproduction to the site maintainer. For a server or resource problem, use the support guide.
qb-inventory
Install QBCore inventory from upstream, check dependencies and SQL, use qb-inventory exports for items, shops and stashes, and diagnose common errors.
qb-shops
Source-verified qb-shops guide: actual shop configuration, stock JSON, delivery jobs, inventory integration and client event security.
