# qb-vehicleshop: dealership setup and finance

`qb-vehicleshop` operates public and job-managed vehicle dealerships, showroom vehicles, test drives, purchases and financed sales. This reference is based on [upstream commit e865297](https://github.com/qbcore-fivem/qb-vehicleshop/tree/e8652970aca3324d2a18a440f3d3871715338da8). The resource is not a generic vehicle-inventory microservice with arbitrary create-sale exports.

## Installation and ownership

1. Start `qb-core`, `oxmysql` and the required `PolyZone` components. Verify `qb-menu`, `qb-input`, vehicle-key, fuel and banking integrations used by your server.
2. Deploy the full `qb-vehicleshop` resource, including locales, `config.lua` and client/server code.
3. Back up the current `player_vehicles` schema and records before comparing the bundled [`vehshop.sql`](https://github.com/qbcore-fivem/qb-vehicleshop/blob/e8652970aca3324d2a18a440f3d3871715338da8/vehshop.sql). **Do not blindly recreate** a shared table that your garage and phone already use.
4. Test a cash purchase, bank purchase, a test drive and a financed vehicle on staging.

The upstream SQL defines/extends **`player_vehicles`**. Standalone tables named `vehicle_sales`, `dealership_inventory` or `vehicle_financing` are **not** created by its bundled SQL.

## Configuration

| Key | Default | Meaning |
| --- | --- | --- |
| `Config.UsingTarget` | Based on `UseTarget` convar | Show target interactions |
| `Config.Commission` | `0.10` | Commission for full sales |
| `Config.FinanceCommission` | `0.05` | Commission for financed sales |
| `Config.PaymentWarning` | `10` | Time before finance-related repossession workflow |
| `Config.PaymentInterval` | `24` | Hours between payments |
| `Config.MinimumDown` | `10` | Minimum down-payment percentage |
| `Config.MaximumPayments` | `24` | Maximum permitted payments |
| `Config.PreventFinanceSelling` | `false` | Prevent transfers of financed vehicles |
| `Config.FilterByMake` | `false` | Show make filter |
| `Config.SortAlphabetically` | `true` | Sort vehicle selectors |
| `Config.Shops` | Dealership definitions | Shop geometry, job, showrooms and test-drive spawns |

Within `Config.Shops.pdm`, the upstream configuration uses `Type`, `Zone`, `Job`, `ShopLabel`, `VehicleSpawn`, `TestDriveSpawn`, `FinanceZone`, `TestDriveTimeLimit` and `ShowroomVehicles`. There is **no** root-level `Config.Dealerships` or `Config.FinancingPlans` in the reviewed file.

## Purchase, finance and storage events

The [server](https://github.com/qbcore-fivem/qb-vehicleshop/blob/e8652970aca3324d2a18a440f3d3871715338da8/server.lua) registers:

| Name | Purpose |
| --- | --- |
| `qb-vehicleshop:server:buyShowroomVehicle` | Public outright purchase flow |
| `qb-vehicleshop:server:financeVehicle` | Public financed purchase |
| `qb-vehicleshop:server:financePayment` / `financePaymentFull` | Payment handling |
| `qb-vehicleshop:server:sellShowroomVehicle` | Job sales workflow |
| `qb-vehicleshop:server:sellfinanceVehicle` | Job finance sales workflow |
| `qb-vehicleshop:server:checkFinance` | Finance state checks |
| QBCore callback `qb-vehicleshop:server:spawnvehicle` | Looks up matching plate and vehicle ownership before spawn |

These are **resource-owned internal events/callbacks**, not stable exports for arbitrary clients. The reviewed server does not register `OpenDealership`, `CreateFinancingPlan` or `UpdateInventory` as public exports.

### Verify vehicle and money ownership

The upstream spawn callback queries `player_vehicles` with **both** plate and the player's citizen ID, then checks model matching. Do not bypass that with a client-supplied `vehicle` or `plate` in your own script. When integrating keys, grant them from a trusted server flow after establishing ownership via [qb-vehiclekeys](/docs/resources/qb-vehiclekeys).

For job-managed vehicle sales, the source uses `exports['qb-banking']:AddMoney(jobName, vehiclePrice, 'Vehicle sale')` to credit a named society account. That is the **banking resource's server export**, not a `qb-vehicleshop` export.

## Troubleshooting

| Symptom | Check |
| --- | --- |
| Vehicles missing from menu | Shared vehicle definitions, categories and `Config.Shops` |
| Showroom/test drive doesn't spawn | Shop zone, spawn point and entity/network ownership |
| Vehicle purchased but not in garage | `player_vehicles` schema, citizen ID, plate and garage integration |
| No car keys after purchase | Server-side vehicle handover and `qb-vehiclekeys:GiveKeys` |
| Financing does not work | `MinimumDown`, payment interval, balance, saved finance fields |
| Society does not receive sale money | Correct named `qb-banking` account initialized |
| No such export `OpenDealership` | This upstream resource does not expose that export |

## Update checklist

1. Pin `qb-vehicleshop`, `qb-core`, `qb-banking`, `qb-vehiclekeys` and garage revisions.
2. Preserve customized shop definitions and back up shared vehicle SQL before updates.
3. Test purchases, vehicle ownership, financed repayments and keys across reconnect.
4. Reject invalid client price/model/down-payment requests on the server.

## Sources

[Repository](https://github.com/qbcore-fivem/qb-vehicleshop/tree/e8652970aca3324d2a18a440f3d3871715338da8) · [Config](https://github.com/qbcore-fivem/qb-vehicleshop/blob/e8652970aca3324d2a18a440f3d3871715338da8/config.lua) · [Server sales/finance](https://github.com/qbcore-fivem/qb-vehicleshop/blob/e8652970aca3324d2a18a440f3d3871715338da8/server.lua) · [Vehicle SQL](https://github.com/qbcore-fivem/qb-vehicleshop/blob/e8652970aca3324d2a18a440f3d3871715338da8/vehshop.sql)
