# 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](https://github.com/qbcore-fivem/qb-shops/tree/16aec230fede3ab8aa453e76a8344aad08fd3706).

## Installation

1. Install `qb-core`, the compatible `qb-inventory` resource and `PolyZone`. Use `qb-target` if the `UseTarget` convar enables target interactions.
2. Deploy `qb-shops` with its `client/`, `server/`, `locale/`, `config.lua` and `json/shops-inventory.json`.
3. Start required resources first, then `qb-shops`. Test buying an existing item from a configured location before adding custom shops.
4. 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`](https://github.com/qbcore-fivem/qb-shops/blob/16aec230fede3ab8aa453e76a8344aad08fd3706/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.

~~~lua filename="config.lua"
-- 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`](https://github.com/qbcore-fivem/qb-shops/blob/16aec230fede3ab8aa453e76a8344aad08fd3706/server/main.lua) uses `qb-shops:server:openShop` to look up a shop by configured key. It then calls:

~~~lua filename="server.lua"
-- 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](/docs/resources/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

1. Pin `qb-shops`, `qb-inventory` and `qb-core` versions together.
2. Back up the stock JSON before replacing the resource; keep custom product/locations changes.
3. Test item purchases, restricted shops and stock persistence across restart.
4. Audit all client-triggerable stock/reward paths for server-side validation.

## Sources

[Repository](https://github.com/qbcore-fivem/qb-shops/tree/16aec230fede3ab8aa453e76a8344aad08fd3706) · [Config](https://github.com/qbcore-fivem/qb-shops/blob/16aec230fede3ab8aa453e76a8344aad08fd3706/config.lua) · [Server inventory integration](https://github.com/qbcore-fivem/qb-shops/blob/16aec230fede3ab8aa453e76a8344aad08fd3706/server/main.lua) · [Manifest](https://github.com/qbcore-fivem/qb-shops/blob/16aec230fede3ab8aa453e76a8344aad08fd3706/fxmanifest.lua)
