Requirements

The included showroom works without an external MLO.

Copying the resource

Place the folder, keeping its original name, inside your resources directory:

resources/
└── [JR]/
    └── JR_DealerShop/

Do not rename JR_DealerShop, because other resources use this name when calling its exports.

Start order

Start every dependency before the dealership:

ensure oxmysql
ensure ox_lib
ensure qb-core

ensure JR_Bridge

# Optional: banking integration and business accounts
ensure JR_Banking

# Select the target resource used by your server
ensure qb-target

# Optional: automatic key delivery
ensure qb-vehiclekeys
ensure JR_DealerShop

If you use ox_target, also update Config.Target.System and Config.Target.Resource in config.lua.

Database

The default configuration uses:

Config.Database = {
    autoMigrate = true,
    keepLegacyJsonBackup = true
}

With autoMigrate = true, the resource only creates missing tables and columns. It does not delete existing vehicles, sales, stock, financing contracts, or dealerships.

If you prefer to install the schema manually, stop the resource and import this file once:

sql/install.sql

Updates that require a database change include a sql/migration_XXX_*.sql file. Do not run a rollback unless you are also restoring the matching older code version.

Administrator permissions

The QBCore admin and god groups are recognized by default. You can also grant access through ACE:

add_ace identifier.license:YOUR_LICENSE jrdealershop.admin allow

Accepted permissions can be changed in Config.Admin.

First verification

After starting the server:

1. Join with an administrator account.
2. Run /jrdealercheck.
3. Review the result in game and in the server console.
4. Run /jrdealer to open the administration panel.
5. Check a dealership, add a low-priced test vehicle, and complete a test purchase.

/jrdealercheck verifies the database, JR_Bridge, active providers, dependencies, and the main integrations.

Updating without losing data

1. Back up your database and config.lua.
2. Stop JR_DealerShop.
3. Replace the resource files with the new version.
4. Restore your custom configuration values.
5. Import the migration mentioned by the update only if automatic migrations are disabled.
6. Start the resource and run /jrdealercheck.

Do not delete the jr_dealershop_* tables during a normal update.

Usage

JR_DealerShop separates global administration, business management, and the customer experience.

Creating or editing a dealership

Use:

/jrdealer

From this panel, an administrator can:

• Create, edit, enable, or disable dealerships.
• Configure the name, categories, blip, and stock usage.
• Place the interaction point and vehicle delivery point.
• Adjust the preview vehicle, camera, and FOV.
• Assign an owner and choose who can manage the business.
• Enable delivery modes, premium paint, and Discord logs.
• Add vehicles with a model, name, price, currency, image, and stock.

Dealerships from Config.InitialDealerships are inserted only on a new installation. After that, changes made through /jrdealer are saved in SQL and are not restored to their default values after a restart.

Preparing the catalogue

The active catalogue is managed through /jrdealer; it is not loaded from Config.Categories[*].vehicles.

Check the following values for every vehicle:

1. Correct spawn model.
2. A category assigned to the dealership.
3. Price and currency.
4. Available stock or unlimited stock.
5. Optional image.

A numeric stock value of 0 means sold out. Unlimited stock is a separate option and never consumes units.

Buying a vehicle

The player opens a dealership from the target or interaction point. Inside the showroom, they can:

• Change vehicle and category.
• Rotate the vehicle or enable automatic rotation.
• Select one of the available colors.
• Apply premium RGB paint when enabled.
• Start a test drive.
• Purchase directly or use financing when the currency allows it.
• Select one of the available delivery methods.

Price, stock, currency, and installment values are validated again by the server. The client never decides the final amount.

Business management

Owners, authorized employees, and administrators use:

/jrdealerboss

The panel provides access to sales, catalogue, stock, employees, financing, orders, showcase vehicles, and the society account.

The default ranks are:

Ranks and permissions can be changed in Config.Employees.ranks.

Assisted sales and commissions

From the Ventas (Sales) tab, an employee can register that they are assisting a nearby player. The customer must accept the request.

If that player purchases from the same dealership within the configured time:

• The sale is linked to the employee.
• The configured commission is calculated.
• The sale income is recorded in the society account.
• The commission is processed safely and persistently.

Ambiguous operations are not repeated blindly. They are marked for manual review, and /jrdealercheck reports them.

Financing

The customer selects a down payment and number of installments within the configured limits. Installments use the currency configured in Config.Financing.paymentCurrency.

Players can view their contracts and pay installments with:

/mydealerfinances

Automatic collection supports two modes:

Config.Financing.automaticPaymentMode = 'online' -- only charge online players
Config.Financing.automaticPaymentMode = 'always' -- also charge offline players when supported by JR_Bridge

Set automaticPayments = false to completely disable automatic payments, automatic missed-payment tracking, and automatic repossession.

Deliveries

Each dealership can offer:

Players can view their pending vehicles with:

/mydealerorders

Customer orders and stock missions

When a vehicle is sold out, the player can place an order if Config.CustomerOrders.enabled = true.

Staff manage these orders from /jrdealerboss → Pedidos (Orders). When stock missions are enabled, the employee must:

1. Accept the order.
2. Start the mission.
3. Collect the transport vehicle from the supplier.
4. Drive the loaded vehicle to the dealership delivery point.
5. Complete the delivery to add exactly one unit to stock.

The current mission can be cancelled with:

/cancelstockmission

If the mission expires, the employee disconnects, or the resource restarts, the order becomes available again without duplicating stock.

3D showroom

The included JR showroom runs in a private instance and does not require an MLO. It includes a custom stage, logo, lighting, cameras, and transitions between vehicles.

Its main settings are located in Config.ShowroomStudio. If it is disabled or the asset cannot load, the script can return to the dealership's physical showroom through fallbackToDealership.

Integrations

JR_Bridge

JR_Bridge is required and acts as the compatibility layer. DealerShop uses it to:

• Identify players and obtain their CitizenID.
• Read, remove, and add money.
• Work with item-based currencies.
• Give vehicle keys through the configured provider.
• Read and modify society accounts.
• Pay commissions to online or offline players when supported.

Configure the framework, inventory, keys, and society provider in JR_Bridge. Do not duplicate those integrations inside DealerShop.

JR_Banking

JR_Banking is optional, but recommended when you want to:

• Display DealerShop financing contracts in the banking interface.
• Pay an installment from a specific bank account.
• Show society deposits and withdrawals in the banking system.

DealerShop never reads or modifies JR_Banking tables directly. Communication is handled exclusively through server exports.

Recommended order:

ensure JR_Bridge
ensure JR_Banking
ensure JR_DealerShop

Target systems

Select the system in config.lua:

Config.Target = {
    Enabled = true,
    System = 'qb-target', -- 'qb-target', 'ox_target', or 'none'
    Resource = 'qb-target'
}

With none or Enabled = false, the dealership uses the proximity prompt and E key.

Vehicle keys

Automatic key delivery depends on the provider configured in JR_Bridge and these options:

Config.Purchase.GiveKeys = true
Config.TestDrive.giveKeys = true

If the vehicle is created correctly but the player does not receive keys, check the active JR_Bridge provider and resource start order first.

Currencies and inventory

Currencies are declared in Config.Currencies:

Config.Currencies = {
    bank = {
        label = 'Bank',
        type = 'money',
        account = 'bank',
        symbol = '$'
    },
    vip = {
        label = 'VIP Coins',
        type = 'item',
        item = 'vipcoin',
        symbol = 'VIP'
    }
}

money currencies use framework accounts. item currencies require the item to exist in the inventory configured through JR_Bridge.

Financing is only offered when the vehicle currency matches the configured installment payment currency.

Society accounts

The global account is configured in Config.SocietyPayments.Account. You can also assign a different account to each dealership:

Config.SocietyPayments.DealershipAccounts = {
    premium = 'cardealer',
    luxury = 'luxurydealer'
}

The provider is resolved through JR_Bridge. If JR_Banking is your society provider, create and configure business accounts there; do not insert them from DealerShop.

Discord

Logs can be enabled and configured per dealership through /jrdealer. You can use one main webhook or separate sales, financing, management, and test-drive webhooks.

Never publish real webhooks in config.lua, repositories, or support screenshots.

Commands and exports

Commands

Most command names can be changed in config.lua.

The following commands only exist when their features are enabled:

Server exports

The exports on this page must be called from server-side code.

Check whether a vehicle is financed

local financed = exports['JR_DealerShop']:IsVehicleFinanced(plate)

if financed then
    print('The vehicle still has an active financing contract')
end

Returns true when the plate belongs to an active or pending-delivery contract.

Financing capabilities for JR_Banking

local capabilities = exports['JR_DealerShop']:GetBankingFinancingCapabilities()

Response:

{
    available = true,
    contractVersion = 1,
    supportsJrBankingAccounts = true,
    supportsIdempotency = true,
    supportsCompensation = true
}

Get a player's financing contracts

local response = exports['JR_DealerShop']:GetBankingFinancings(source)

if response.success then
    for _, finance in ipairs(response.results) do
        print(finance.finance_id, finance.plate, finance.payments_left)
    end
end

DealerShop obtains the CitizenID from JR_Bridge and only returns contracts owned by the specified player.

Pay an installment through JR_Banking

local result = exports['JR_DealerShop']:PayBankingFinancingInstallment(source, {
    finance_id = '15',
    account_number = 'JR123456',
    idempotency_key = 'dealer:15:checkout-uuid'
})

if result.success then
    print(result.payment_amount, result.payments_left, result.status)
else
    print(result.error)
end

The idempotency_key must be unique to one payment intent and reused for every retry of that same operation. Do not generate a new key when repeating a request that did not return a response.

DealerShop reads the authoritative installment amount from its own database. The consumer does not send or control the amount.

A successful response normally contains:

{
    success = true,
    payment_amount = 850,
    payments_left = 4,
    status = 'active',
    operation_id = '...',
    tx_ref = '...',
    payment_confirmed = true,
    society_credit = 'credited'
}

If the operation remains under reconciliation, also check warning, payment_confirmed, and society_credit before showing a final status to the player.

Common errors

The resource does not start

Check the server.cfg start order. At minimum, oxmysql, ox_lib, qb-core, and JR_Bridge must be running before JR_DealerShop.

Then run:

/jrdealercheck

The dealership interaction does not appear

• Confirm that the dealership is enabled.
• Review its interaction coordinates through /jrdealer.
• Make sure Config.Target.System matches the installed target resource.
• If you do not use a target resource, select none and try the E interaction.

The catalogue is empty

Vehicles are not loaded from Config.Categories[*].vehicles. Add them through /jrdealer and assign the matching category to the dealership.

Then run /reloaddealership or restart the resource.

The player pays but does not receive the vehicle

Check the following in order:

1. Server console and the player's F8 console.
2. Vehicle spawn model.
3. Delivery coordinates and available space.
4. Garage integration and the player_vehicles table.
5. Active key provider in JR_Bridge.

Do not repeat purchases manually in SQL. First check whether the sale and plate were already recorded.

Society deposits or withdrawals do not work

• Run /jrdealercheck and verify the society provider.
• Confirm that the configured account exists and is active.
• When using JR_Banking, it must start after JR_Bridge and before DealerShop.
• Check Config.SocietyPayments.Account and every value in DealershipAccounts.

The financing option does not appear

• Config.Financing.enabled must be enabled.
• The vehicle currency must match Config.Financing.paymentCurrency.
• The down payment and number of installments must respect the configured limits.
• To pay from the banking interface, JR_Banking must be running and compatible with the DealerShop contract.

The showroom is black, empty, or displays the map

• Make sure you copied the stream folder and the files inside html/images.
• Do not rename or remove jr_showroom_stage_v8.ydr or jr_showroom_stage_v8.ytyp.
• Clear the client cache after replacing an older stage version.
• Check F8 with Config.Debug = true if the asset does not load.
• As a temporary fallback, disable Config.ShowroomStudio.enabled to use the physical showroom.

The stock mission does not finish

• The employee who started the mission must drive the transport.
• Use the transport vehicle created by the mission.
• Enter the dealership delivery radius and respect the minimum driving time.
• The mission cannot finish if the order state already changed or the mission expired.
• Use /cancelstockmission and reassign the order if the transport becomes stuck.

A society credit or commission is marked for manual review

Do not force the payment again. This state prevents duplicate money when a restart or ambiguous response occurs between resources.

Run /jrdealercheck, save the relevant console lines, and review the operation before correcting it.

What to send to support

Include:

• JR_DealerShop, JR_Bridge, and JR_Banking versions.
• /jrdealercheck result.
• Full server console error.
• F8 error when the problem affects the interface, camera, or vehicle.
• Exact reproduction steps.
• Framework, target, inventory, keys, and society provider in use.

Remove passwords, tokens, and webhooks before sharing screenshots or files.