# 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`](https://github.com/qbcore-fivem/qb-inventory/tree/dc3d07fc60139de569df38c5ac178ed4cada4577)
(September 11, 2026), including
[server/functions.lua](https://github.com/qbcore-fivem/qb-inventory/blob/dc3d07fc60139de569df38c5ac178ed4cada4577/server/functions.lua),
[server/hooks.lua](https://github.com/qbcore-fivem/qb-inventory/blob/dc3d07fc60139de569df38c5ac178ed4cada4577/server/hooks.lua),
[server/main.lua](https://github.com/qbcore-fivem/qb-inventory/blob/dc3d07fc60139de569df38c5ac178ed4cada4577/server/main.lua)
and [client/main.lua](https://github.com/qbcore-fivem/qb-inventory/blob/dc3d07fc60139de569df38c5ac178ed4cada4577/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](/diagrams/inventory.svg)

*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](/docs/resources/qb-inventory).

## 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.

```lua
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.

```lua
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 |

- `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](https://github.com/qbcore-framework/qb-docs/blob/930c12ec4f60dfbba60253571f1a58980129516d/qbcore-resources/qb-inventory.md#hooks--listeners).

## 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.

```lua
-- 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:

| 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](/docs/api/server-functions) 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

- [qb-inventory installation and exports](/docs/resources/qb-inventory)
- [Inventory update troubleshooting](/docs/troubleshooting/inventory-updates)
- [Safe server events](/docs/security/safe-server-events)
