API Reference

This page is for developers integrating another resource with oxide-shops. All exports listed here are server-side and are the only public integration surface. Every export below is verified against the resource code.

If you only run the resource, you don't need anything here — this is for scripting.

Server Exports

Shop Queries

GetShop

Returns the full record for one shop, or nil if it doesn't exist.

local shop = exports['oxide-shops']:GetShop('247supermarket')

Parameters:

Name	Type	Description
shopId	string	The shop's unique ID

Returns: table|nil — the shop record. Notable fields: shopId, type ('static' or 'player'), ownerCharId, name, pedModel, coords, chairs, balance, purchasePrice, resalePrice, style, job, minRank, dutyOnly, hideBlip, blip.

GetAllShops

Returns every shop, keyed by shop ID.

local shops = exports['oxide-shops']:GetAllShops()
for shopId, shop in pairs(shops) do
    print(shopId, shop.name, shop.type)
end

Returns: table — a map of shopId → shop record.

GetShopsByOwner

Returns every shop owned by a character.

local owned = exports['oxide-shops']:GetShopsByOwner(charId)

Parameters:

Name	Type	Description
charId	string	A character identifier (the same ID `o-link` uses for a character)

Returns: table[] — an array of shop records (empty if the character owns none).

Shop Balance

GetShopBalance

Returns a shop's current till balance.

local balance = exports['oxide-shops']:GetShopBalance('mycustomshop')

Parameters:

Name	Type	Description
shopId	string	The shop's unique ID

Returns: number — the balance, or 0 if the shop doesn't exist.

AddBalance

Adds money to a shop's till.

exports['oxide-shops']:AddBalance('mycustomshop', 500)

Parameters:

Name	Type	Description
shopId	string	The shop's unique ID
amount	number	Amount to add

Returns: boolean — true on success, false if the shop doesn't exist.

RemoveBalance

Removes money from a shop's till.

local ok, err = exports['oxide-shops']:RemoveBalance('mycustomshop', 500)

Parameters:

Name	Type	Description
shopId	string	The shop's unique ID
amount	number	Amount to remove

Returns: boolean, string|nil — true on success; otherwise false and an error ('shop_not_found' or 'insufficient_balance').

Shop Stock

GetStock

Returns a shop's stock table.

local stock = exports['oxide-shops']:GetStock('247supermarket')
-- stock['water'] = { quantity = -1, price = 4, category = 'Food & Drink', autoRestockTarget = nil }

Parameters:

Name	Type	Description
shopId	string	The shop's unique ID

Returns: table — a map of itemName → { quantity, price, category, autoRestockTarget }. A quantity of -1 means unlimited (static shops).

AddStock

Adds to an item's stock (no effect on unlimited/static items).

exports['oxide-shops']:AddStock('mycustomshop', 'water', 25)

Parameters:

Name	Type	Description
shopId	string	The shop's unique ID
itemName	string	The item to add
amount	number	Quantity to add

Returns: none.

RemoveStock

Removes from an item's stock.

local ok = exports['oxide-shops']:RemoveStock('mycustomshop', 'water', 5)

Parameters:

Name	Type	Description
shopId	string	The shop's unique ID
itemName	string	The item to remove
amount	number	Quantity to remove

Returns: boolean — true on success (also true for unlimited items); false if the item doesn't exist or there isn't enough stock.

Ownership

TransferOwnership

Transfers a player-owned shop to a different character, keeping its stock, price book, and balance.

local ok = exports['oxide-shops']:TransferOwnership('mycustomshop', newCharId)

Parameters:

Name	Type	Description
shopId	string	The shop's unique ID
newCharId	string	The character to hand the shop to

Returns: boolean — true on success; false if the shop doesn't exist or isn't player-owned.

ReclaimShop

Returns a player-owned shop to server-run (static) status: clears the owner and balance and restores unlimited stock.

local ok, err = exports['oxide-shops']:ReclaimShop('mycustomshop')

Parameters:

Name	Type	Description
shopId	string	The shop's unique ID

Returns: boolean, string|nil — true on success; otherwise false and an error ('shop_not_found' or 'not_player_owned').

Settings

GetSetting

Reads the live value of any top-level configuration key (the database-backed value, which may differ from the file default).

local taxRate = exports['oxide-shops']:GetSetting('TaxRate')

Parameters:

Name	Type	Description
key	string	A `Config` key name (e.g. `'TaxRate'`, `'MaxShopsPerPlayer'`)

Returns: any — the current value, or nil if the key doesn't exist.

SetSetting

Sets a configuration key live, persists it to the database, and mirrors it to clients. This is the same path the /shop settings menu uses.

exports['oxide-shops']:SetSetting('TaxRate', 0.08)

Parameters:

Name	Type	Description
key	string	A `Config` key name
value	any	The new value

Returns: boolean — true.

This export is not permission-gated. If you expose it to players in any way, gate it yourself. The in-game menu re-checks admin permission before calling it.

Events

oxide-shops uses internal events to sync shops between the server and clients. These are implementation details and are not a stable integration API — they may change between versions. Use the exports above instead of listening to internal events.

There are no public client exports.

Integration Examples

Example: Read a player's owned shops

-- Server-side. Get the shops a player owns via o-link's character identifier.
local olink = exports['o-link']:olink()

local function getPlayerShops(source)
    local charId = olink.character.GetIdentifier(source)
    if not charId then return {} end
    return exports['oxide-shops']:GetShopsByOwner(charId)
end

Example: Pay a commission into a shop's till

-- Add a bonus to a shop balance when your resource does business with it.
local function payCommission(shopId, amount)
    if exports['oxide-shops']:GetShop(shopId) then
        exports['oxide-shops']:AddBalance(shopId, amount)
    end
end

Next Steps

Features — what the data means in-game
Admin — managing shops without code

On this page