QBCore Frameworkqbcore.netCommunity docs
On this page

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.

Inventory events, server state and synchronization

Conceptual diagram; verify the behavior against your installed resource version.

Choose the right API

TaskInterfaceSide
Add or remove itemsexports['qb-inventory']:AddItem / RemoveItemServer
Check item ownership or capacityHasItem / CanAddItem exportsServer
Open a trusted stashexports['qb-inventory']:OpenInventoryServer
Reject a supported operationexports['qb-inventory']:AddHookServer
Observe a completed operationexports['qb-inventory']:AddListenerServer
Check an item for local UIexports['qb-inventory']:HasItemClient
Show an item-box notificationqb-inventory:client:ItemBoxClient

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:

TypeOperation
ItemMovedMove, give, stack, split, or swap items
ItemDroppedDrop an item into the world
ItemUsedUse an inventory item
ItemBoughtBuy a shop item
ItemAddedAdd an item through a supported external path
ItemRemovedRemove an item through a supported external path
InventoryOpenedOpen an inventory
ShopOpenedOpen 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

ExportUsage
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
  • ItemMoved callback: function(moveKind, data) where moveKind is given, stacked, split, swapped, or moved. The payload includes fromId, fromType, fromInventory, toId, toType, toInventory, fromSlot, toSlot and amount.
  • ItemAdded callback: function(itemType, data). This is the one hook that can also return a table to replace item.info before insertion.
  • ItemRemoved callback: function(itemType, data), with fromId, fromType, fromInventory, fromSlot, item, amount, reason, resource.
  • ItemUsed callback: function(itemType, data), with source, sourceInventory and item.
  • InventoryOpened callback: function(inventoryType, data), with source, sourceInventory, inventoryId and inventory.
  • ShopOpened callback: function(shopType, data), with source, sourceInventory and shop.

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'
    )
end

Use 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:

EventSideRole
qb-inventory:server:closeInventoryServerInventory close bookkeeping
qb-inventory:server:useItemServerInventory item-use transport
qb-inventory:server:SetInventoryDataServerInventory slot-move transport
qb-inventory:server:openDropServerInventory drop transport
qb-inventory:client:openInventoryClientOpen UI
qb-inventory:client:updateInventoryClientRefresh UI (case-sensitive)
qb-inventory:client:ItemBoxClientVisual notification
qb-inventory:client:closeInvClientClose 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.

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.

On this page

Leonida RP server website built with RPWebsite
RPWebsite

Advertisement · RPWebsite

Want a website for your server?

Launch a site with live player status, rules, and a join button in minutes.

Build your website