# Working with item metadata in ox_inventory

> Use item metadata in ox_inventory: built-in keys like durability, serial and components, adding items with metadata, SetMetadata and displayMetadata.

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

**Short answer.** Pass metadata when creating an item — `exports.ox_inventory:AddItem(src, 'id_card', 1, { name = 'John Doe' })` — and change it later with `SetMetadata(inv, slot, metadata)`. Built-in keys include `durability`, `serial`, `registered`, `ammo`, `components`, `label`, `description`, `image` and `weight`. Show your own keys in the tooltip with `displayMetadata` on the client, and fill metadata automatically with a `createItem` hook.

## Key points

- Metadata = a table stored per item stack.
- Items with different metadata do not stack together.
- `label`, `description`, `image`, `weight` override the item definition per stack.
- `displayMetadata` shows custom keys in tooltips.
- `createItem` hooks can set metadata for every new item.

Metadata is what makes two items with the same name different: this pistol’s serial, that phone’s number, a letter’s text, a bottle half full. In ox_inventory it is a Lua table stored with each item stack, and a few keys have built-in meaning.

## Keys with built-in meaning

| Key | Effect |
| --- | --- |
| `durability` | 0–100 condition; also used by degrading items and weapons |
| `serial` | Weapon serial number |
| `registered` | Registered owner for weapons (`false` = no serial) |
| `ammo` | Loaded ammo in a weapon |
| `components` | Attachments on a weapon |
| `label` | Custom display name for this stack |
| `description` | Custom tooltip text |
| `image` | Custom image for this stack |
| `weight` | Extra weight for this stack |

## Adding and changing metadata

*server.lua*

```lua
-- create with metadata
exports.ox_inventory:AddItem(src, 'id_card', 1, {
    label = 'ID — John Doe',
    description = 'DOB 1994-03-12',
    citizenid = 'ABC12345',
})

-- change an existing stack
local slot = exports.ox_inventory:GetSlotWithItem(src, 'water')
if slot then
    local meta = slot.metadata
    meta.durability = 50
    exports.ox_inventory:SetMetadata(src, slot.slot, meta)
end
```

## Finding items by metadata

*server.lua*

```lua
-- count ID cards that belong to this citizen
local count = exports.ox_inventory:Search(src, 'count', 'id_card', { citizenid = 'ABC12345' })
```

## Showing custom metadata

*client.lua*

```lua
exports.ox_inventory:displayMetadata({
    citizenid = 'Citizen ID',
    plate = 'Plate',
})
```

Now any item with those keys shows them in its tooltip with your labels.

## Setting metadata automatically

*server.lua — stamp every new ID card*

```lua
exports.ox_inventory:registerHook('createItem', function(payload)
    local meta = payload.metadata
    meta.issued = os.date('%Y-%m-%d')
    return meta
end, { itemFilter = { id_card = true } })
```

A `createItem` hook may return a table, which becomes the item’s metadata. Weapon serials use the same system — see [serial numbers](https://fam-tools.com/guides/fivem-weapon-serial-numbers).

## Questions

### What is metadata in ox_inventory?

A table of extra data stored with each item stack, such as durability, serial or custom fields.

### How do I give an item a custom name?

Set `label` in its metadata when you add it.

### Why do my items not stack?

Stacks with different metadata stay separate.

### How do I show custom metadata in the tooltip?

Call `exports.ox_inventory:displayMetadata({ key = 'Label' })` on the client.

## Related

- https://fam-tools.com/guides/ox-inventory-items-lua
- https://fam-tools.com/guides/ox-inventory-hooks
- https://fam-tools.com/guides/fivem-weapon-serial-numbers
- https://fam-tools.com/guides/fivem-weapon-durability