# Developer

> Developer API reference for ML Shops

Category: SHOPS SYSTEM · Source: https://miciomods.it/docs/ml-shops-developer · Last updated: 2026-08-14

## Overview

ML Shops provides exports for other resources. Handler hooks live in the `open/` folder.

## Client Exports

**your_script/client.lua**

```lua
exports['ml_shops']:openShop(shopId)
```

- `openShop(shopId)`: Opens the shop UI for a specific shop
- `GetShopData(shopId)`: Returns shop configuration data
- `GetTraderData(traderId)`: Returns trader configuration data
- `GetAllShops()`: Returns all registered shops
- `GetAllTraders()`: Returns all registered traders
- `GetPlayerDiscount(source, shopId, itemId)`: Returns the player's current discount for a shop
- `CalculateFinalPrice(source, shopId, itemId)`: Returns the discounted cost table and the discount percent
- `SetItemStock(shopId, itemName, amount)`: Overrides item stock
- `AddItemStock(shopId, itemName, amount)`: Adds stock to an item
- `IsShopOpen(source, shopId)`: Returns whether the player may use the shop, plus an optional reason
- `TriggerShopRefresh(shopId)`: Forces a UI refresh for a shop

## Server Handlers

Defined in `open/server.lua`.

**open/server.lua**

```lua
function OpenServer.BeforeGiveItem(src, item, amount)
    return true -- return false to block the purchase
end

function OpenServer.OnActionComplete(src, actionType, data)
    -- Fired after any shop action completes
end
```

- `BeforeGiveItem(src, item, amount)`: Called before giving a purchased item. Return `false` to block.
- `OnActionComplete(src, actionType, data)`: Fires after purchase, stock change, or other actions.

## Client Handlers

Defined in `open/handlers_client.lua`.

**open/handlers_client.lua**

```lua
Handlers.BeforeOpenUI = function(data)
    return true -- return false to block the shop UI
end

Handlers.CanOpenShop = function(shopId, traderData)
    return true -- return false, 'reason' to block and notify
end
```

> **INFO:** Notification System
>
> Notifications go through `ml_bridge`. `Config.Notify` in `ml_bridge/config.lua` selects the system: auto, ox, qb, esx, wasabi, okok, mythic, pnotify, tnotify, brutal, lation, r_notify, fl, zsx.

## Shared Handlers

Defined in `open/shared.lua`.

**open/shared.lua**

```lua
function OpenHandlers.OnPlayerAction(src, data)
    return true -- return false to block
end

function OpenHandlers.ValidateAction(src, actionType)
    return true -- return false to reject
end
```

- `OnPlayerAction`: Global hook for any player action
- `ValidateAction`: Validates an action before execution

## Examples

**Block Purchases for Specific Jobs**

**open/server.lua**

```lua
function OpenServer.BeforeGiveItem(src, item, amount)
    local job = Bridge.GetPlayerJob(src)
    if job and job.name == 'police' then
        Bridge.NotifyPlayer(src, 'error', 'Police cannot purchase here.')
        return false
    end
    return true
end
```

**Open a Shop from Another Script**

**your_script/client.lua**

```lua
exports['ml_shops']:openShop('general_store_1')
```