esx_shops

esx_shops is the official store resource for ESX Legacy. It places 24/7, Rob's Liquor and LTD Gasoline stores on the map and opens a Svelte-based shopping cart UI where players pick items, choose cash or bank and pay. Use it as your general store system or as a template for your own item shops.

OverviewCopy Anchor Link

How a purchase works:

1. The player walks into a marker and presses the interaction key. The client asks the server for the player's tax rate and opens the NUI.
2. On checkout the client sends the cart through the esx_shops:purchaseItems callback.
3. The server rate-limits the request, checks the zone, the distance to the shop, the payment method, every item name, quantity and price against Config.Zones, and recomputes the total. The client total must match the server total within Config.PriceTolerance.
4. The server checks inventory weight, deducts money and adds the items. If adding an item fails, already added items are removed and the money is refunded.
5. The tax part of the price is deposited into Config.TaxSocietyAccount when tax collection is on.

InstallationCopy Anchor Link

ensure oxmysql
ensure esx_lib
ensure es_extended
ensure esx_addonaccount
ensure esx_shops

INSERT IGNORE INTO `addon_account` (`name`, `label`, `shared`) VALUES ('society_banker', 'Bank', 1);

With Config.Inventory = 'esx' the resource registers every configured shop item via ESX.AddItems on startup (label, weight or Config.DefaultItemWeight). You still want proper rows in your items table for items you use elsewhere.

ConfigurationCopy Anchor Link

Main config (shared/config/main.lua)Copy Anchor Link

Shop zones (shared/config/shops.lua)Copy Anchor Link

Config.Zones ships with three zones: TwentyFourSeven, RobsLiquor and LTDgasoline. Each zone looks like this:

Config.Zones.Hardware = {
    Items = {
        { name = 'repairkit', label = 'Repair Kit', price = 250, category = 'tools', weight = 2 },
        { name = 'bandage', label = 'Bandage', price = 40, category = 'medical' },
    },
    Categories = {
        { id = 'tools', label = 'Tools', icon = 'fa-solid fa-wrench' },
        { id = 'medical', label = 'Medical', icon = 'fa-solid fa-kit-medical' },
    },
    Pos = {
        vector3(2748.0, 3473.0, 55.7),
    },
    Size = 0.8,     -- blip scale
    Type = 59,      -- blip sprite
    Color = 25,     -- blip color
    ShowBlip = true,
    ShowMarker = true,
}

Tax mathCopy Anchor Link

Prices include tax. For a 100 item at a TaxRate of 0.19, a normal player pays 100 and 15.97 goes to the society account. A tax-exempt player pays 84.03 and no tax is collected.

The UI colors follow the ESX theme convars (esx:ui:*) via xLib.colors.getESXTheme.

Developer APICopy Anchor Link

Server export IsItemInShopCopy Anchor Link

exports.esx_shops:IsItemInShop(itemName, zone)

Returns true when the item is sold in that zone, otherwise false.

if exports.esx_shops:IsItemInShop('lockpick', 'TwentyFourSeven') then
    print('Lockpicks are sold in 24/7 stores')
end

Shared exports GetShopItems / GetShopCategoriesCopy Anchor Link

Both are available on client and server and are marked as legacy. They return the Items or Categories table of a zone, or {} if the zone does not exist.

local items = exports.esx_shops:GetShopItems('RobsLiquor')

Client exportsCopy Anchor Link

Client event esx_shops:forceOpenShopCopy Anchor Link

Opens the shop UI for a zone if it exists in Config.Zones.

TriggerClientEvent('esx_shops:forceOpenShop', playerId, 'TwentyFourSeven')

Purchases still require the player to stand within 5 meters of one of that zone's Pos entries, so this is only useful near a real shop location (for example from a target or ped script).

Callbacks and network eventsCopy Anchor Link

Common issuesCopy Anchor Link

• "Not enough money" although the player has cash. The payment method chosen in the UI decides between money and bank.
• Tax is not deposited. Config.TaxSocietyAccount does not exist in addon_account, or esx_addonaccount is not started. Enable Config.Debug to see the warning.
• Item not added / inventory full. With the ESX inventory, every item must be registered and fit the player's max weight. With ox_inventory, CanCarryItem must succeed.
• Images missing. Put a PNG named after the item into web/images or set image on the item.
• Shop opens but purchases fail far from the marker. See the distance check above.

RelatedCopy Anchor Link

• esx_addonaccount
• esx_weaponshop
• Adding items
• ox_inventory with ESX

Frequently asked questions