QBCore Frameworkqbcore.netCommunity docs
On this page

4 min read

qb-inventory

qb-inventory is QBCore's inventory resource. It owns player/item storage behavior, registered inventories and shops, drops, UI opening, persistence helpers, inventory hooks/listeners and the player item methods it attaches while the resource is running.

Use the resource exports instead of directly mutating inventory tables.

qb-inventory request and state synchronization

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

For opening failures, use inventory diagnostics. Before replacing this resource, read the ox_inventory bridge and migration checks.

Download and install qb-inventory

For QBCore inventory, use the upstream qb-inventory repository. The qb-core download is the framework core, not the inventory resource. Setting up a whole server? See Download QBCore and the txAdmin recipe before installing individual resources.

The upstream README lists qb-core and qb-smallresources for logging as dependencies. Check the manifest, configuration and README at your selected commit as well; forks can have different requirements.

  1. Back up your resource files and database. Work on a staging copy first.
  2. Download or clone the upstream repository, record its commit, and keep the resource folder named qb-inventory inside your [qb] group.
  3. For a fresh install, review and import the repository's qb-inventory.sql into the intended server database. Do not import it blindly over an existing inventory installation.
  4. For an upgrade, follow the SQL and migration instructions for your existing and target revisions. Validate migrated player inventories and stashes before removing any old tables; keep a restorable backup.
  5. Start the dependencies before inventory and any resources consuming its exports. Check the first server-console error before testing the UI.
  6. Test item use, capacity limits, shops, stashes, reconnects and persistence after a server restart.

For UI-only changes, use the qb-inventory reskin guide. For failed opens or item operations, jump to troubleshooting or inventory update troubleshooting.

Start order

A normal QBCore setup starts the core before inventory consumers:

ensure qb-core
ensure [qb]

When debugging, confirm qb-inventory itself is started before a custom resource calls its exports. See Resource load order.

Current server exports

The current server/functions.lua exposes inventory operations including:

  • OpenInventory
  • OpenInventoryById
  • CreateInventory
  • GetInventory
  • RemoveInventory
  • AddItem
  • RemoveItem
  • CanAddItem
  • CreateShop
  • OpenShop
  • ClearStash

The exact source file contains additional helpers. Pin your integration to the revision you deploy.

Add an item

local added = exports['qb-inventory']:AddItem(
    source,
    'water_bottle',
    1,
    false,
    false,
    'my-resource:reward'
)

if not added then
    -- Handle full/invalid inventory.
end

Remove an item

local removed = exports['qb-inventory']:RemoveItem(
    source,
    'water_bottle',
    1,
    false,
    'my-resource:consume'
)

Check capacity before adding

local canAdd, reason = exports['qb-inventory']:CanAddItem(source, 'water_bottle', 1)
if not canAdd then
    print(reason) -- for example weight or slots
    return
end

Create and open a custom inventory

exports['qb-inventory']:CreateInventory('evidence-123', {
    label = 'Evidence 123',
    maxweight = 100000,
    slots = 30
})

exports['qb-inventory']:OpenInventory(source, 'evidence-123')

Treat identifiers as server-owned values when access matters. Do not let a client choose an arbitrary stash name and then open it without authorization.

Player methods

Current qb-inventory adds item methods to connected QBCore player objects, including AddItem, RemoveItem, item lookup, ClearInventory and SetInventory.

That compatibility layer comes from qb-inventory, not from the permanent qb-core API. Direct inventory exports make ownership clearer in new integrations.

Inventory busy state

The resource uses the player state bag inv_busy to prevent conflicting opens/moves.

Before building a custom UI that manipulates inventory, understand when the resource sets or clears that state rather than introducing a second independent lock.

Shops

Register server-defined shops through the current inventory API instead of sending authoritative prices from the client.

A shop definition should be built on the server from trusted config, then opened for the player through the inventory's shop path.

For QBCore's dedicated shop resource, see qb-shops.

Hooks and listeners

Current qb-inventory exposes server-side AddHook and AddListener exports for operations such as opening an inventory, moving items, and adding or removing them. Hooks can reject a supported operation before it completes; listeners observe completed operations.

See the source-verified hooks, payloads and event reference for runnable registration examples, event names and differences between hooks, listeners and UI transport events. Always authorize inventory access in your server resource; a hook is not a substitute for the caller's own permission checks.

Persistence

Player inventory is synchronized with the QBCore player object and persisted by the inventory/core integration. Non-player inventories are handled by qb-inventory's own storage paths.

Do not create random tables such as player_items, stashitems or trunkitems because an old tutorial used them. Import only SQL shipped by the repository/recipe version you deploy.

Security pattern

For a reward:

RegisterNetEvent('myjob:server:claimReward', function(jobId)
    local src = source
    local Player = exports['qb-core']:GetPlayer(src)
    if not Player then return end

    -- Validate jobId, player state, proximity, cooldown and ownership server-side.
    local reward = resolveTrustedReward(jobId)
    if not reward then return end

    exports['qb-inventory']:AddItem(src, reward.name, reward.amount, false, false, 'myjob:reward')
end)

The client may request an action; it should not decide item names, quantities, prices or reward eligibility.

Troubleshooting

SymptomCheck
Inventory will not openResource state, first console error, inv_busy, and caller API version.
AddItem returns falseItem exists in shared items, available slots/weight, correct identifier.
Item shows no imageItem definition image name and files in the inventory UI assets.
A stash can be opened by anyoneAuthorization is missing in the calling server resource.
Old export/event is missingCompare your code against current server/functions.lua and migration notes.

See Inventory update troubleshooting and the events/functions reference.

If you replace the default inventory instead of patching it, compare inventory scripts on RPScripts by declared QBCore version, dependencies and data migration path. RPScripts and qbcore.net are operated by the same owner.

Sources

Source references and literal export names rechecked against commit dc3d07fc on 2026-10-13. This is static evidence, not FXServer or database acceptance.

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