Updated 2026-10-11 · 3 min read
qb-shops: configuring stores and inventory
qb-shops defines purchasable items and physical shop locations, manages configured stock/delivery flows and opens shops through qb-inventory. This guide describes upstream commit 16aec23.
Installation
- Install
qb-core, the compatibleqb-inventoryresource andPolyZone. Useqb-targetif theUseTargetconvar enables target interactions. - Deploy
qb-shopswith itsclient/,server/,locale/,config.luaandjson/shops-inventory.json. - Start required resources first, then
qb-shops. Test buying an existing item from a configured location before adding custom shops. - Verify every product item exists in the QBCore shared item list.
No SQL schema is bundled with this revision of qb-shops. The old shop_items or shop_receipts example tables are not part of the official code. Persistent delivery shop stock is written to the configured JSON file; player inventory persistence belongs to the deployed inventory implementation.
Configuration keys
The config.lua defines these major settings:
| Setting | What it controls |
|---|---|
Config.UseTarget | UseTarget convar-driven interaction mode |
Config.Products | Product categories/arrays, item names, prices and amounts |
Config.Locations | Physical shops, products, markers, access and stock mode |
Config.ShopsInvJsonFile | Stock persistence file: ./json/shops-inventory.json |
Config.TruckDeposit | Delivery-vehicle deposit (default 125) |
Config.MaxDeliveries | Delivery amount cap (default 20) |
Config.DeliveryPrice | Delivery-job payment setting (default 500) |
Config.RewardItem | Delivery bonus item (default cryptostick) |
Config.Fuel | Fuel integration namespace (default LegacyFuel) |
Config.DeliveryLocations / Config.Vehicles | Delivery routes and vehicles |
The built-in Config.Products.normal array includes items such as water_bottle, sandwich and bandage. Modify entries in the actual category or shop; do not invent Config.ShopSettings, Config.ProductCategories, Config.Economy or an auto-restock interval from another script.
-- Example item inside the existing Config.Products.normal array:
{ name = 'water_bottle', price = 2, amount = 50 },Edit the upstream config in context. This is a table entry, not a self-contained config file.
Shop opening and inventory API ownership
The real server/main.lua uses qb-shops:server:openShop to look up a shop by configured key. It then calls:
-- From a server-owned shop flow after validating shop and player:
exports['qb-inventory']:CreateShop({
name = shopName,
label = shopData.label,
slots = shopData.slots,
coords = shopData.coords,
items = items,
})
exports['qb-inventory']:OpenShop(source, shopName)These two functions are qb-inventory server exports, not qb-shops exports. The resource does not export OpenShop, AddShop, UpdateShopStock, RestockShop or SetItemPrice. Use qb-inventory for the shop registration API.
Internal stock and delivery events
The server registers qb-shops:server:RestockShopItems, UpdateShopItems, DoBail, PaySlip and openShop. These are internal flows, not permission-safe public extension points.
In the current UpdateShopItems handler, a caller-supplied shop, item slot and amount adjust configured stock and write to Config.ShopsInvJsonFile. Your production resource should verify the actual purchase/stock change on the server rather than trusting arbitrary event payloads. Respect the inventory resource's own transaction and authorization rules.
Troubleshooting
| Symptom | Check |
|---|---|
| Shop interaction is missing | UseTarget, PolyZone/target availability and Config.Locations |
| Item is not for sale | Exact Config.Products item name, slot and QBCore.Shared.Items |
No such export OpenShop in qb-shops | The export belongs to qb-inventory on the server |
| Shop stock resets after reboot | Writable json/shops-inventory.json and persistence errors |
| Product costs or permissions incorrect | Item price and job/grade restriction in the deployed config and inventory |
| Delivery job fails | Deposit balance, configured vehicle, route and fuel namespace |
Update checklist
- Pin
qb-shops,qb-inventoryandqb-coreversions together. - Back up the stock JSON before replacing the resource; keep custom product/locations changes.
- Test item purchases, restricted shops and stock persistence across restart.
- Audit all client-triggerable stock/reward paths for server-side validation.
Sources
Repository · Config · Server inventory integration · Manifest
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.
