what item records currently belong to a character, location, or other container owner
where each item currently is
whether an item move, split, merge, equip, or consume action is valid
which specific item instance is being traded, auctioned, or transferred

This service should not own:

Ownership model

every inventory record has an ownerType and ownerId
USER can read and mutate items owned by their own characters
USER can read and mutate location/container items only when gameplay rules allow it
SUPER can read and mutate any inventory item
access should be resolved through the current owner, not from the item id alone

Initial design

Use one MongoDB document per inventory item record.

Practical interpretation:

Reasons:

every item or stack gets a stable UUID, which is useful for auctions, trade, mail, and auditing
ownership transfer is explicit and cheap: update ownerType, ownerId, and slot fields
future item metadata like durability, rarity rolls, or provenance can live on the item document
auction listings can point to specific item ids instead of vague stack descriptions

Tradeoffs:

GET /api/inventory/by-owner/{ownerType}/{ownerId} Return all item records currently owned by that container owner.
POST /api/inventory/by-owner/{ownerType}/{ownerId}/grant Create a new item record or add quantity into an existing compatible stack.
POST /api/inventory/by-owner/{ownerType}/{ownerId}/move Move an item or stack within the same owner inventory.
POST /api/inventory/transfer Move quantity from one owner inventory to another.
POST /api/inventory/items/{itemId}/consume Consume quantity from a specific item record.
POST /api/inventory/items/{itemId}/equip Equip a specific item into a character equipment slot.
POST /api/inventory/items/{itemId}/unequip Return an equipped item to a character inventory slot.

Notes:

equip and unequip only make sense for character-owned items
transfer is the core world interaction primitive for looting, dropping, trading, chest interaction, and auction handoff
a future AuctionApi can reserve or re-own specific item ids without redesigning InventoryApi

Every inventory record should have a stable UUID string such as:

Each record also carries an itemKey such as:

Recommended distinction:

id: unique item-record identifier used for ownership changes, auctions, and references
itemKey: item definition identifier used to decide stackability and gameplay behavior

Each item document should include:

Optional future fields:

an item record must belong to exactly one owner at a time
stackable items may share itemKey but should still be represented by one stack record per occupied slot
non-stackable items must always have quantity = 1
equipped items should set equippedSlot and clear slot
unequipped bag items should set slot and clear equippedSlot
slot occupancy must be unique per (ownerType, ownerId, slot)
all mutating endpoints should be idempotent where practical

The Godot client should fetch all items for the currently relevant owner and group them into a bag view locally.

Good pattern:

login/select character
GET /api/inventory/by-owner/character/{characterId}
when opening a stash or world container: GET /api/inventory/by-owner/location/{locationId}
cache the returned item records locally
call transfer/equip/consume endpoints using specific itemId values
replace local state with the server response after each mutation