# Controlling inventory actions with ox_inventory hooks

> Use ox_inventory event hooks: registerHook for swapItems, openShop, buyItem, createItem and craftItem, filters, cancelling actions and removeHooks.

Source: https://fam-tools.com/guides/ox-inventory-hooks · FAM Tools · published 2026-09-11 · updated 2026-09-11 · about 11 min

**Short answer.** On the server, `exports.ox_inventory:registerHook(event, function(payload) ... end, options)` runs your function before an action. Events include `swapItems`, `openInventory`, `openShop`, `buyItem`, `createItem`, `usingItem` and `craftItem`. Return `false` to cancel (for `createItem`, return a table to set metadata). Narrow hooks with `itemFilter`, `inventoryFilter` (Lua patterns) and `typeFilter`, keep them fast, and remove them with `removeHooks`.

## Key points

- Hooks run server-side before the action.
- `return false` cancels it.
- Filters keep hooks cheap: `itemFilter`, `inventoryFilter`, `typeFilter`.
- Hooks slower than about 10 ms are reported as warnings.
- Hooks are removed automatically when your resource stops.

Sooner or later every server needs rules the inventory does not have: no weapons in the evidence locker, no drugs in vehicle gloveboxes, a Discord log for every high-value transfer. ox_inventory’s hooks let your resource inspect an action on the server and cancel it — without editing the inventory itself.

## Hook events

| Event | Runs when |
| --- | --- |
| `swapItems` | Items move between slots or inventories (move, stack, swap, give) |
| `openInventory` | An inventory (stash, trunk…) is opened |
| `openShop` | A shop is opened |
| `buyItem` | A shop purchase is made |
| `createItem` | An item is created (can return metadata) |
| `usingItem` | An item is about to be used |
| `craftItem` | A crafting recipe is completed |

## Example: no weapons in gloveboxes

*server.lua*

```lua
local WEAPONS = {}
for name in pairs(exports.ox_inventory:Items()) do
    if name:find('^WEAPON_') then WEAPONS[name] = true end
end

exports.ox_inventory:registerHook('swapItems', function(payload)
    if payload.toType == 'glovebox' then
        TriggerClientEvent('ox_lib:notify', payload.source, { type = 'error', description = 'Weapons do not fit in the glovebox' })
        return false
    end
end, {
    itemFilter = WEAPONS,
    print = false,
})
```

`itemFilter` is a set of item names; the hook only runs when one of them is involved, so everyday item moves cost nothing.

## Filters

| Option | Form | Matches |
| --- | --- | --- |
| `itemFilter` | `{ water = true, WEAPON_PISTOL = true }` | Item names |
| `inventoryFilter` | `{ '^glove', '^trunk', 'evidence' }` | Inventory IDs by Lua pattern |
| `typeFilter` | `{ player = true, stash = true }` | Inventory or shop type |
| `print` | `true` | Log each time the hook triggers |

## Example: logging high-value transfers

*server.lua*

```lua
exports.ox_inventory:registerHook('swapItems', function(payload)
    if payload.fromInventory ~= payload.toInventory and payload.count >= 10000 then
        print(('[inv] %s moved %s x%d from %s to %s'):format(
            payload.source, payload.fromSlot.name, payload.count, payload.fromInventory, payload.toInventory))
    end
end, { itemFilter = { money = true, black_money = true } })
```

## Performance and cleanup

- Hooks run inside the action — no database calls or HTTP requests in them.
- Use filters instead of `if` checks at the top of the function.
- `registerHook` returns an ID; `exports.ox_inventory:removeHooks(id)` removes one, and all of a resource’s hooks are removed when it stops.

Related: [stashes](https://fam-tools.com/guides/ox-inventory-stashes), [shops](https://fam-tools.com/guides/ox-inventory-shops-config) and [item metadata](https://fam-tools.com/guides/ox-inventory-metadata).

## Questions

### How do I stop players moving an item in ox_inventory?

Register a `swapItems` hook with an `itemFilter` and return `false` when the move is not allowed.

### Which events can ox_inventory hooks use?

`swapItems`, `openInventory`, `openShop`, `buyItem`, `createItem`, `usingItem` and `craftItem`.

### How do I set metadata when an item is created?

Return a metadata table from a `createItem` hook.

### Do hooks slow down the inventory?

Only if they are slow or unfiltered. Keep them fast and use filters.

## Related

- https://fam-tools.com/guides/ox-inventory-stashes
- https://fam-tools.com/guides/ox-inventory-metadata
- https://fam-tools.com/guides/ox-inventory-shops-config
- https://fam-tools.com/guides/fivem-weapon-anticheat-validation