ESX vs QB Core: Setting Up Refunds for Each Framework

ESX and QB Core dominate the FiveM ecosystem, but their inventory systems, database schemas, and event structures differ significantly. Getting refunds working smoothly requires understanding these nuances. This guide walks through setup for both frameworks so you can pick the path that fits your server.

A good refund setup is not just a command that adds an item. It needs to identify the right player, target the correct inventory system, preserve metadata, update audit records, and fail safely when the server is offline or the player has no space. ESX and QB Core can both support that workflow, but they solve the details differently.

Database schema differences

ESX traditionally stores player data across multiple tables (users, user_inventory, user_accounts), while QB Core consolidates most data into a single players table with JSON columns. LD Refund System adapts automatically, but custom queries need adjustment.

• ESX: Items stored in `user_inventory` with item name and count columns
• QB Core: Items stored as JSON in `players.inventory` column
• Both: Money typically split into cash, bank, and sometimes crypto accounts

Before you configure refunds, confirm which inventory resource is authoritative. Many ESX servers use ox_inventory or qs-inventory instead of the original ESX inventory table. Many QB Core servers customize qb-inventory or move to ox_inventory. Your refund script should follow the actual production inventory resource, not just the base framework label.

Configuring item refunds on ESX

ESX uses xPlayer:addInventoryItem() and xPlayer:removeInventoryItem() for inventory operations. Ensure your items exist in the database items table and match the exact name string. Weight limits apply if you're using a weight-based inventory like ox_inventory.

1. Verify the player identifier format used by your ESX build
2. Confirm item names against your live item registry
3. Test online and offline refund delivery separately
4. Check that money refunds target the right account name, such as bank or money

-- ESX item refund example
local xPlayer = ESX.GetPlayerFromId(source)
xPlayer:addInventoryItem('bandage', 5)
xPlayer:addAccountMoney('bank', 50000)

Configuring item refunds on QB Core

QB Core relies on exports from qb-inventory or qb-core directly. Items must be registered in qb-core/shared/items.lua. The functions AddItem and RemoveItem handle quantity, but metadata support varies by inventory resource.

For QB Core, the most common mistake is mixing citizenid, source, and Discord ID during staff workflows. Discord can identify the staff member and player account, but the actual refund should resolve to the correct citizenid before touching inventory or money. LD Refund System’s lookup flow is designed to make that selection explicit for staff.

-- QB Core item refund example
local Player = QBCore.Functions.GetPlayer(source)
Player.Functions.AddItem('bandage', 5)
Player.Functions.AddMoney('bank', 50000, 'refund')

Weapon refunds: metadata matters

Weapons often carry metadata like serial numbers, attachments, and ammo counts. On ESX with ox_inventory, weapon metadata is stored as JSON. QB Core's qb-weapons similarly tracks serials. LD Refund System preserves this metadata when issuing weapon refunds, but custom scripts must handle serialization carefully.

• Store serial number, ammo, durability, tint, and components where available
• Avoid generating duplicate serials unless your policy requires replacement weapons
• Log metadata before and after delivery so staff can resolve disputes
• Reject weapon refunds when required metadata is missing instead of issuing incomplete items

Performance considerations

Both frameworks perform similarly for refund operations since the heavy lifting happens on the Discord bot side. However, QB Core's JSON columns can be slower to query at scale. For servers with 200+ concurrent players, consider indexing strategies or caching frequently accessed player data.

Test the full refund lifecycle

Do not stop testing after a single item appears in inventory. Run through item, money, weapon, vehicle, online player, offline player, full inventory, cancelled refund, and duplicate claim cases. Each scenario should leave a clear audit record and a predictable player-facing result.

Also test framework upgrades separately from refund changes. ESX, QB Core, QBox, and inventory resources can change exports or metadata behavior between versions. Keep a small staging checklist with one known item, one money refund, one weapon with metadata, and one offline claim so you can validate compatibility before pushing updates to production.

Whichever framework you run, the key is consistency. Pick one approach, document your item registry, and train staff on the exact refund flow.