Configuration Reference

Every setting in all eight oxide-dealerships config files, with types, defaults, and behavior notes.

Every setting in oxide-dealerships, what it does, and its default value. To change one, edit the file, save, and restart the resource or your server so the change takes effect.

Config files set the rules — the database holds the shops

The actual dealerships in your world — where each lot is, its map blip, the greeter NPC, test-drive spawn points, accepted payment methods, and job restrictions — are not in these files. They live in the database and are edited in-game with the admin commands and dashboard.

Config File Map

File	Covers
`shared/config.lua`	General settings, the tablet, manual sales, commission, repossession, wholesale, the preview scene, the showroom
`shared/config/vehicles.lua`	The vehicle catalog — which models exist and their prices
`shared/config/finance.lua`	Financing terms
`shared/config/payments.lua`	Payment methods (cash, bank, items)
`shared/config/coupons.lua`	Promo code rules
`shared/config/tradein.lua`	Trade-in values
`shared/config/email.lua`	In-character email toggles
`shared/config/showcase_hud.lua`	The look-and-hold stat card over display cars

shared/config.lua

General

Setting	Type	Default	Description
`Config.Debug`	boolean	`false`	Draws each dealership's lot-zone outline on screen in-game so you can see placed zones during setup. It does not add server console output.

Management Tablet

Controls the windowed dashboard owners and staff open at the lot.

Setting	Type	Default	Description
`Config.Tablet.holdAnim`	boolean	`true`	Plays a tablet-holding animation while the dashboard is open.
`Config.Tablet.radialId`	string	`'oxide-dealerships:radial:manage'`	Internal id of the radial-menu entry that opens the tablet inside the lot. You normally never change this.
`Config.Tablet.command`	string	`'managedealership'`	The chat command that opens the tablet. Do not set this to `dealership` — that name is reserved for the admin command.

Manual Sales

Controls the in-person Sales Desk where a salesperson sells to a nearby buyer.

Setting	Type	Default	Description
`Config.ManualSale.buyerRadius`	number	`5.0`	How close (in meters) the buyer must stand to the salesperson.
`Config.ManualSale.offerTimeoutSec`	number	`60`	A pending contract expires after this many seconds if the buyer doesn't sign.
`Config.ManualSale.maxConcurrentPerSeller`	number	`1`	How many pending offers one salesperson may have at once.
`Config.ManualSale.ownerEarnsCommission`	boolean	`false`	Whether an owner selling their own stock earns commission.
`Config.ManualSale.minPriceOverridePct`	number	`50`	The lowest custom price a salesperson may set, as a percent of the listing price. `50` means a $100,000 listing can't be sold under $50,000. `0` removes the limit.

Commission and Duty

Setting	Type	Default	Description
`Config.OnDutyRadius`	number	`80.0`	How close (in meters) an employee must be to the greeter when a walk-in sale closes to earn commission on it.

Used and Repossession

Setting	Type	Default	Description
`Config.UsedPriceDiscount`	number	`0.65`	A repossessed vehicle is re-listed for sale at this fraction of the original financed amount (the price minus the down payment). `0.65` = 65%.
`Config.NpcSentinelCharId`	string	`'oxide-npc'`	A placeholder owner id used internally for vehicles repossessed by an NPC dealership. Only change it if it would clash with a real character id on your server.

Wholesale

Setting	Type	Default	Description
`Config.Dealerships.WholesaleMultiplier`	number	`0.70`	The wholesale cost a player-owned shop pays per vehicle when ordering stock, as a fraction of the catalog price. `0.70` = owners buy in at 70% and resell at their own price.

Catalog Preview Scene (advanced)

Controls the 3D preview that opens when a player views a vehicle. Most owners never touch this — the defaults are tuned for the shipped car, boat, and aircraft shops.

Setting	Type	Default	Description
`Config.CatalogScene.ground`	table	shipped coords	Vehicle position, camera position, and field of view for the ground (car/bike) preview.
`Config.CatalogScene.sea`	table	shipped coords	Same, for boats.
`Config.CatalogScene.air`	table	shipped coords	Same, for aircraft.
`Config.CatalogScene.closeDistance`	number	`5.0`	If the player walks more than this many meters from the greeter, the preview closes.
`Config.CatalogScene.sway`	table	`Speed 1.0, X 0.12, Y 0.08, Z 0.08, Fov 1.5`	The gentle camera drift that keeps the preview feeling alive. Lower these if it feels seasick.
`Config.CatalogScene.colors`	table	18 preset swatches	The paint colors offered in the preview, each an `{ r, g, b }` triple.
`Config.CatalogScene.rotateSpeed`	number	`60.0`	How fast (degrees per second) the previewed car spins when the player holds A or D.
`Config.CatalogScene.rotateSmooth`	number	`8.0`	How smoothly the spin eases in and out.

shared/config.lua

Config.CatalogScene = {
    ground = {
        vehicle = vec4(227.23, -988.16, -99.00, 300.91),
        camera  = vec4(232.36, -988.16, -98.96, 90.16),
        fov     = 50.0,
    },
    sea = {
        vehicle = vec4(-798.32, -1500.60, -0.6, 109.73),
        camera  = vec4(-801.69, -1491.53, 2.13, 200.86),
        fov     = 40.0,
    },
    air = {
        vehicle = vec4(-979.09, -2995.52, 12.95, 328.83),
        camera  = vec4(-987.15, -2991.58, 14.47, 241.20),
        fov     = 40.0,
    },
    closeDistance = 5.0,
    sway = { Speed = 1.0, X = 0.12, Y = 0.08, Z = 0.08, Fov = 1.5 },
    colors = {
        { label = 'Black', r = 13, g = 17, b = 22 },
        -- ...17 more preset colors...
    },
    rotateSpeed  = 60.0,
    rotateSmooth = 8.0,
}

Showroom

Setting	Type	Default	Description
`Config.Showroom.rotateSpeed`	number	`8.0`	Default turntable spin speed (degrees per second) for a display slot with rotation enabled but no speed of its own.

shared/config/vehicles.lua

The catalog: every vehicle that can be sold, and which shops sell it. Each entry is one model, keyed by its spawn name:

shared/config/vehicles.lua

V['adder'] = { label = 'Adder', brand = 'Truffade', price = 280000, category = 'super', type = 'automobile', shopList = { 'luxury' } }

Field	Type	Description
`label`	string	The display name shown in the catalog.
`brand`	string	The manufacturer shown in the catalog.
`price`	number	The catalog price in dollars.
`category`	string	The grouping in the catalog (e.g. `compacts`, `sedans`, `suvs`, `super`, `boats`, `helicopters`).
`type`	string	The vehicle type used when spawning: `automobile`, `bike`, `boat`, `heli`, or `plane`.
`shopList`	table	Which shop ids this model is sold at, e.g. `{ 'pdm' }`. A model can be sold at more than one shop.

The shipped catalog is the standard QBCore vehicle list, assigned to four shops: pdm (cars and bikes), boats, air, and truck. A luxury shop assignment exists for the optional Luxury dealership (see Installation).

Adding your own car

Add a new line with the vehicle's spawn name as the key, then restart the resource:

shared/config/vehicles.lua

V['mycar'] = { label = 'My Custom Car', brand = 'Custom', price = 150000, category = 'super', type = 'automobile', shopList = { 'pdm' } }

The blocklist

Config.VehiclesBlocklist is a list of spawn names excluded from every catalog no matter what — emergency, military, and special vehicles. Add any model here that should never be buyable.

shared/config/vehicles.lua

Config.VehiclesBlocklist = {
    'police', 'police2', 'police3', 'police4',
    'sheriff', 'sheriff2',
    'ambulance', 'firetruk',
    'fbi', 'fbi2',
    'riot', 'pbus',
    'lazer', 'hydra', 'cargobob', 'rhino',
    'apc', 'barracks', 'barracks2', 'barracks3',
}

shared/config/finance.lua

All the rules for vehicle financing. See Financing for how the loan lifecycle plays out.

Setting	Type	Default	Description
`Config.Finance.enabled`	boolean	`true`	Turns financing on or off entirely.
`Config.Finance.minDownPct`	number	`10`	The minimum down payment, as a percentage of the price.
`Config.Finance.minPayments`	number	`2`	The fewest installments a buyer may choose.
`Config.Finance.maxPayments`	number	`24`	The most installments a buyer may choose.
`Config.Finance.paymentIntervalMinutes`	number	`60`	Minutes between automatic payment collections.
`Config.Finance.maxMissedBeforeDefault`	number	`3`	The loan defaults (and the car is repossessed) on this many missed payments — with `3`, the third miss triggers it.
`Config.Finance.missWhileOffline`	boolean	`false`	What happens when a payment comes due while the buyer is offline. `false`: the due date pushes forward and the loan pauses until they return. `true`: the payment counts as missed — a pressure tactic that makes players log in to keep loans current.
`Config.Finance.baseInterestPct`	number	`8`	The standard interest rate added to the financed amount.
`Config.Finance.maxRatePct`	number	`30`	The highest interest rate a salesperson may set on a manual finance sale. The rate is clamped between 0 and this value.
`Config.Finance.schedulerTickMs`	number	`60000`	How often (in milliseconds) the system checks for due payments. `60000` = once a minute.
`Config.Finance.dueSoonNoticeSeconds`	number	`24 * 3600`	How far ahead (in seconds) a payment counts as "coming up soon" for the login reminder. Default is 24 hours.
`Config.Finance.useOxideBanking`	boolean	`false`	When `true` and `oxide-banking` is running, credit scores adjust interest rates and an invoice for the outstanding balance is sent when a loan defaults. Otherwise financing uses the flat base rate.

shared/config/payments.lua

Defines how buyers can pay. Read Payment Methods for the important item-payment behavior before enabling item methods.

Setting	Type	Default	Description
`Config.Payments.financeAccount`	string	`'bank'`	The money account financing always uses for the down payment and installments.
`Config.Payments.methods`	table	Cash and Bank	The list of payment methods.

Each method entry:

Field	Type	Description
`id`	string	A unique id for the method.
`label`	string	The name shown at checkout.
`icon`	string	A Font Awesome icon name shown next to the method.
`type`	string	`money` (draws from a money account) or `item` (spends an inventory item).
`account`	string	For money methods: which account to charge (e.g. `cash`, `bank`).
`item`	string	For item methods: which inventory item to spend (one item = one dollar).
`default`	boolean	When `true`, every shop accepts this method unless overridden.
`enabled`	boolean	Set to `false` to hide a method. Omit it to keep the method on.

shared/config/payments.lua

Config.Payments = {
    financeAccount = 'bank',

    methods = {
        { id = 'cash', label = 'Cash', icon = 'fa-money-bill-wave', type = 'money', account = 'cash', default = true },
        { id = 'bank', label = 'Bank', icon = 'fa-building-columns', type = 'money', account = 'bank', default = true },

        -- Examples — set enabled = true to offer them:
        -- { id = 'crypto',    label = 'Crypto',    icon = 'fa-coins', type = 'money', account = 'crypto',    enabled = false },
        -- { id = 'vip_token', label = 'VIP Token', icon = 'fa-star',  type = 'item',  item = 'vip_token',    enabled = false },
        -- { id = 'casino',    label = 'Casino Chips', icon = 'fa-dice', type = 'item', item = 'casino_chip', enabled = false },
    },
}

Item methods are a money sink

An item method consumes the item and grants the car, but does not credit a player-owned shop's reserve balance and pays no commission. Only money methods do those.

shared/config/coupons.lua

Promo code rules. See Coupons and Promo Codes.

Setting	Type	Default	Description
`Config.Coupons.enabled`	boolean	`true`	Turns the coupon system on or off.
`Config.Coupons.allowOwnerCreated`	boolean	`false`	When `false`, shop owners cannot create promo codes and the Promotions app is hidden. Set to `true` to let owners run their own sales. Admins can always create codes regardless.
`Config.Coupons.codeMinLength`	number	`3`	The shortest a promo code may be.
`Config.Coupons.codeMaxLength`	number	`32`	The longest a promo code may be. Do not raise this above 32 — the database column only holds 32 characters.
`Config.Coupons.maxPercent`	number	`100`	The largest percentage discount a code may apply.
`Config.Coupons.minFinalPrice`	number	`1`	A discount can never bring the final price below this — there is always at least a token charge.

shared/config/tradein.lua

Trade-in values and payout rules. See Trade-Ins.

Setting	Type	Default	Description
`Config.TradeIn.enabled`	boolean	`true`	Turns trade-ins on or off.
`Config.TradeIn.independentRate`	number	`0.45`	The automatic greeter offer, as a fraction of the vehicle's value. The value used is the price the vehicle last sold for at a dealership (never more than its catalog price), so a car bought at a discount can't be traded back in for more than was paid.
`Config.TradeIn.cooldownMinutes`	number	`10`	How long a customer must wait between trade-ins. Stops players from rapidly cycling vehicles into payouts. `0` removes the wait.
`Config.TradeIn.minOffer`	number	`0`	A floor on the automatic offer. `0` = no floor.
`Config.TradeIn.maxOffer`	number	`0`	A ceiling on the automatic offer. `0` = no ceiling.
`Config.TradeIn.resaleRate`	number	`0.65`	The price the traded car is re-listed at, as a fraction of its catalog price. Kept above `independentRate` so the shop makes a margin.
`Config.TradeIn.allowFinanceCredit`	boolean	`true`	Whether a trade-in's value may be applied toward a financed purchase's down payment.
`Config.TradeIn.payoutAccounts`	table	`{ 'cash', 'bank' }`	The money accounts a customer may cash out a trade-in into.

Financed vehicles can't be traded in

A vehicle with an unpaid finance loan has to be paid off before it can be traded in.

shared/config/email.lua

On/off switches for in-character emails. Emails need a phone resource that o-link supports; if none is installed they are simply skipped and the on-screen notifications still work.

Setting	Type	Default	Description
`Config.Email.enabled`	boolean	`true`	Master switch for all dealership emails.
`Config.Email.employment`	boolean	`true`	Hiring (welcome) and firing (separation) notices.
`Config.Email.receipts`	boolean	`true`	Purchase receipts and signed financing agreements.
`Config.Email.financing`	boolean	`true`	Due-soon reminders, missed-payment notices, repossession notices, and paid-off confirmations.
`Config.Email.sellerCommission`	boolean	`true`	The "sale closed" notice sent to the salesperson.

shared/config/showcase_hud.lua

The floating stat card that appears over a showroom display vehicle when a player looks at it and holds a key.

Setting	Type	Default	Description
`Config.ShowcaseHud.enabled`	boolean	`true`	Turns the showcase card on or off.
`Config.ShowcaseHud.holdKey`	number	`19`	The key the player holds to show the card. `19` is Left Alt.
`Config.ShowcaseHud.maxDistance`	number	`8.0`	The farthest (in meters) the card will appear.
`Config.ShowcaseHud.heightOffset`	number	`1.4`	How high (in meters) above the car the card floats.
`Config.ShowcaseHud.nearDist`	number	`4.0`	At or under this distance the card is at its largest.
`Config.ShowcaseHud.farDist`	number	`8.0`	At or beyond this distance the card is at its smallest.
`Config.ShowcaseHud.scaleMin`	number	`0.7`	The smallest the card scales to.
`Config.ShowcaseHud.scaleMax`	number	`1.0`	The largest the card scales to.

Config File Map

shared/config.lua

General

Management Tablet

Manual Sales

Commission and Duty

Used and Repossession

Wholesale

Catalog Preview Scene (advanced)

Showroom

shared/config/vehicles.lua

Adding your own car

The blocklist

shared/config/finance.lua

shared/config/payments.lua

shared/config/coupons.lua

shared/config/tradein.lua

shared/config/email.lua

shared/config/showcase_hud.lua

Next Steps

Admin

Features

Troubleshooting

On this page