> For the complete documentation index, see [llms.txt](https://docs.17movement.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.17movement.net/vending-machines/exports-and-api/client-exports.md).

# Client Exports

### `getOwnedMachines`

Returns all vending machines the player owns or works at.

#### Usage

```lua
local machines = exports['17mov_VendingMachines']:getOwnedMachines()
```

#### Returns

An array of machines:

<table data-search="false"><thead><tr><th>Field</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code>id</code></td><td><code>number</code></td><td>Machine ID</td></tr><tr><td><code>coords</code></td><td><code>table</code></td><td>Machine coordinates</td></tr><tr><td><code>balance</code></td><td><code>number</code></td><td>Current machine balance</td></tr><tr><td><code>stock.used</code></td><td><code>number</code></td><td>Currently used stock space</td></tr><tr><td><code>stock.total</code></td><td><code>number</code></td><td>Total stock capacity</td></tr><tr><td><code>label</code></td><td><code>string?</code></td><td>Custom machine label</td></tr><tr><td><code>role</code></td><td><code>string</code></td><td>Player's role for this machine</td></tr><tr><td><code>permissions</code></td><td><code>table</code></td><td>Player's permissions for this machine</td></tr><tr><td><code>street</code></td><td><code>string</code></td><td>Street name resolved from the machine location</td></tr></tbody></table>

#### Example

```lua
local machines = exports['17mov_VendingMachines']:getOwnedMachines()

for _, machine in ipairs(machines) do
    print(machine.id, machine.label, machine.balance)
end
```

***

### `getMapMachines`

Returns a lighter version of the player's machines intended for map integrations.

Unlike `getOwnedMachines`, this does not include labels or detailed permissions.

#### Usage

```lua
local machines = exports['17mov_VendingMachines']:getMapMachines()
```

#### Returns

An array of machines:

| Field             | Type     | Description                    |
| ----------------- | -------- | ------------------------------ |
| `id`              | `number` | Machine ID                     |
| `role`            | `string` | Player's role for this machine |
| `balance`         | `number` | Current machine balance        |
| `stock`           | `table`  | Current stock information      |
| `location.coords` | `table`  | Machine coordinates            |

#### Example

```lua
local machines = exports['17mov_VendingMachines']:getMapMachines()

for _, machine in ipairs(machines) do
    print(machine.id, machine.location.coords)
end
```

***

## Sales & History

### `getSales`

Returns revenue statistics from the last 7 days across all machines the player owns.

The entries are returned from the oldest day to the newest.

#### Usage

```lua
local sales = exports['17mov_VendingMachines']:getSales()
```

#### Returns

| Field     | Type     | Description                |
| --------- | -------- | -------------------------- |
| `date`    | `string` | Date of the entry          |
| `count`   | `number` | Number of purchases        |
| `revenue` | `number` | Revenue generated that day |

#### Example

```lua
local sales = exports['17mov_VendingMachines']:getSales()

for _, day in ipairs(sales) do
    print(day.date, day.count, day.revenue)
end
```

***

### `getHistory`

Returns purchase history for the player's vending machines.

Each call returns up to **25 purchases**, newest first.

#### Usage

```lua
local history = exports['17mov_VendingMachines']:getHistory(machineId, before)
```

#### Parameters

| Parameter   | Type     | Required | Description                                                         |
| ----------- | -------- | -------- | ------------------------------------------------------------------- |
| `machineId` | `number` | ❌        | Machine to filter by. Leave empty to include all owned machines     |
| `before`    | `number` | ❌        | ID of the last purchase from the previous page, used for pagination |

#### Returns

<table data-search="false"><thead><tr><th>Field</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code>id</code></td><td><code>number</code></td><td>Purchase ID</td></tr><tr><td><code>machine_id</code></td><td><code>number</code></td><td>Machine ID</td></tr><tr><td><code>buyer_name</code></td><td><code>string</code></td><td>Buyer name</td></tr><tr><td><code>item_name</code></td><td><code>string</code></td><td>Inventory item name</td></tr><tr><td><code>item_label</code></td><td><code>string</code></td><td>Display label of the item</td></tr><tr><td><code>price</code></td><td><code>number</code></td><td>Purchase price</td></tr><tr><td><code>created_at</code></td><td><code>number</code></td><td>Purchase timestamp</td></tr></tbody></table>

#### Example

```lua
local history = exports['17mov_VendingMachines']:getHistory(12)

for _, purchase in ipairs(history) do
    print(purchase.buyer_name, purchase.item_label, purchase.price)
end
```

#### Pagination

Pass the ID of the last entry from the previous page:

```lua
local nextPage = exports['17mov_VendingMachines']:getHistory(12, 1500)
```

***

## Machine Settings

### `getMachineSettings`

Returns editable settings for a machine.

This returns `nil` if the player is not the owner.

#### Usage

```lua
local settings = exports['17mov_VendingMachines']:getMachineSettings(machineId)
```

#### Parameters

| Parameter   | Type     | Required | Description |
| ----------- | -------- | -------- | ----------- |
| `machineId` | `number` | ✅        | Machine ID  |

#### Returns

| Field               | Type      | Description                      |
| ------------------- | --------- | -------------------------------- |
| `label`             | `string?` | Custom machine label             |
| `lowStockThreshold` | `number`  | Low-stock notification threshold |

Or `nil` if the player does not own the machine.

#### Example

```lua
local settings = exports['17mov_VendingMachines']:getMachineSettings(12)

if settings then
    print(settings.label, settings.lowStockThreshold)
end
```

***

### `saveMachineSettings`

Updates the machine label and low-stock threshold.

#### Usage

```lua
local result = exports['17mov_VendingMachines']:saveMachineSettings(
    machineId,
    label,
    lowStockThreshold
)
```

#### Parameters

| Parameter           | Type      | Required | Description             |
| ------------------- | --------- | -------- | ----------------------- |
| `machineId`         | `number`  | ✅        | Machine ID              |
| `label`             | `string?` | ❌        | New machine label       |
| `lowStockThreshold` | `number`  | ✅        | New low-stock threshold |

#### Returns

| Field               | Type      | Description                     |
| ------------------- | --------- | ------------------------------- |
| `success`           | `boolean` | Whether the settings were saved |
| `message`           | `string?` | Optional response message       |
| `label`             | `string?` | Saved machine label             |
| `lowStockThreshold` | `number?` | Saved low-stock threshold       |

#### Example

```lua
local result = exports['17mov_VendingMachines']:saveMachineSettings(
    12,
    'Legion Vending',
    5
)

if result.success then
    print('Settings saved')
end
```

***

## Notifications

### `getNotifications`

Returns the player's current notification preferences.

#### Usage

```lua
local notifications = exports['17mov_VendingMachines']:getNotifications()
```

#### Returns

| Field        | Type      | Description             |
| ------------ | --------- | ----------------------- |
| `lowStock`   | `boolean` | Low-stock notifications |
| `sales`      | `boolean` | Sales notifications     |
| `deliveries` | `boolean` | Delivery notifications  |

#### Example

```lua
local notifications = exports['17mov_VendingMachines']:getNotifications()

print(notifications.lowStock)
print(notifications.sales)
print(notifications.deliveries)
```

***

### `saveNotifications`

Updates the player's notification preferences.

You only need to provide the options you want to change.

#### Usage

```lua
local result = exports['17mov_VendingMachines']:saveNotifications({
    lowStock = true,
    sales = true,
    deliveries = false
})
```

#### Parameters

| Field        | Type       | Required | Description                               |
| ------------ | ---------- | -------- | ----------------------------------------- |
| `lowStock`   | `boolean?` | ❌        | Enable or disable low-stock notifications |
| `sales`      | `boolean?` | ❌        | Enable or disable sales notifications     |
| `deliveries` | `boolean?` | ❌        | Enable or disable delivery notifications  |

#### Returns

| Field           | Type      | Description                        |
| --------------- | --------- | ---------------------------------- |
| `success`       | `boolean` | Whether the preferences were saved |
| `message`       | `string?` | Optional response message          |
| `notifications` | `table?`  | Updated notification preferences   |

***

## Workers

### `getWorkers`

Returns all workers assigned to a machine.

#### Usage

```lua
local workers = exports['17mov_VendingMachines']:getWorkers(machineId)
```

#### Parameters

| Parameter   | Type     | Required | Description |
| ----------- | -------- | -------- | ----------- |
| `machineId` | `number` | ✅        | Machine ID  |

#### Returns

| Field         | Type                     | Description        |
| ------------- | ------------------------ | ------------------ |
| `identifier`  | `string`                 | Worker identifier  |
| `name`        | `string`                 | Worker name        |
| `permissions` | `table<string, boolean>` | Worker permissions |

#### Example

```lua
local workers = exports['17mov_VendingMachines']:getWorkers(12)

for _, worker in ipairs(workers) do
    print(worker.name, worker.identifier)
end
```

***

### `addWorker`

Adds an online player as a worker.

The player specified by `targetId` must currently be online.

#### Usage

```lua
local result = exports['17mov_VendingMachines']:addWorker(
    machineId,
    targetId,
    permissions
)
```

#### Parameters

| Parameter     | Type                     | Required | Description                     |
| ------------- | ------------------------ | -------- | ------------------------------- |
| `machineId`   | `number`                 | ✅        | Machine ID                      |
| `targetId`    | `number`                 | ✅        | Server ID of the player to hire |
| `permissions` | `table<string, boolean>` | ✅        | Worker permissions              |

Available permissions:

| Permission | Description             |
| ---------- | ----------------------- |
| `restock`  | Restock the machine     |
| `order`    | Place wholesaler orders |
| `collect`  | Collect machine revenue |
| `workers`  | Manage workers          |

#### Returns

| Field       | Type       | Description                  |
| ----------- | ---------- | ---------------------------- |
| `success`   | `boolean`  | Whether the worker was added |
| `message`   | `string?`  | Optional response message    |
| `employees` | `table[]?` | Updated worker list          |

#### Example

```lua
local result = exports['17mov_VendingMachines']:addWorker(12, 27, {
    restock = true,
    order = true,
    collect = false,
    workers = false
})
```

***

### `setWorkerPermissions`

Updates permissions for an existing worker.

Use the `identifier` returned by `getWorkers()`.

#### Usage

```lua
local result = exports['17mov_VendingMachines']:setWorkerPermissions(
    machineId,
    identifier,
    permissions
)
```

#### Parameters

| Parameter     | Type                     | Required | Description                                  |
| ------------- | ------------------------ | -------- | -------------------------------------------- |
| `machineId`   | `number`                 | ✅        | Machine ID                                   |
| `identifier`  | `string`                 | ✅        | Worker identifier returned by `getWorkers()` |
| `permissions` | `table<string, boolean>` | ✅        | New permission set                           |

#### Returns

| Field       | Type       | Description                          |
| ----------- | ---------- | ------------------------------------ |
| `success`   | `boolean`  | Whether the permissions were updated |
| `message`   | `string?`  | Optional response message            |
| `employees` | `table[]?` | Updated worker list                  |

#### Example

```lua
local result = exports['17mov_VendingMachines']:setWorkerPermissions(
    12,
    identifier,
    {
        restock = true,
        order = true,
        collect = true,
        workers = false
    }
)
```

***

### `removeWorker`

Removes a worker from a machine.

#### Usage

```lua
local result = exports['17mov_VendingMachines']:removeWorker(
    machineId,
    identifier
)
```

#### Parameters

| Parameter    | Type     | Required | Description       |
| ------------ | -------- | -------- | ----------------- |
| `machineId`  | `number` | ✅        | Machine ID        |
| `identifier` | `string` | ✅        | Worker identifier |

#### Returns

| Field       | Type       | Description                    |
| ----------- | ---------- | ------------------------------ |
| `success`   | `boolean`  | Whether the worker was removed |
| `message`   | `string?`  | Optional response message      |
| `employees` | `table[]?` | Updated worker list            |

***

## Wholesaler

### `getWholesalerCatalog`

Returns all products currently available from the wholesaler.

Products are returned with their inventory label and image.

#### Usage

```lua
local catalog = exports['17mov_VendingMachines']:getWholesalerCatalog()
```

#### Returns

| Field   | Type      | Description         |
| ------- | --------- | ------------------- |
| `item`  | `string`  | Inventory item name |
| `label` | `string`  | Display label       |
| `price` | `number`  | Wholesaler price    |
| `image` | `string?` | Item image          |

#### Example

```lua
local catalog = exports['17mov_VendingMachines']:getWholesalerCatalog()

for _, product in ipairs(catalog) do
    print(product.label, product.price)
end
```

***

### `getWholesalerOrders`

Returns wholesaler orders for a machine.

#### Usage

```lua
local orders = exports['17mov_VendingMachines']:getWholesalerOrders(machineId)
```

#### Parameters

| Parameter   | Type     | Required | Description |
| ----------- | -------- | -------- | ----------- |
| `machineId` | `number` | ✅        | Machine ID  |

#### Returns

Each order contains:

| Field    | Type      | Description                 |
| -------- | --------- | --------------------------- |
| `id`     | `number`  | Order ID                    |
| `status` | `string`  | Current order status        |
| `items`  | `table[]` | Items included in the order |

Each item contains:

| Field        | Type     | Description              |
| ------------ | -------- | ------------------------ |
| `item_name`  | `string` | Inventory item name      |
| `item_label` | `string` | Display label            |
| `quantity`   | `number` | Ordered quantity         |
| `remaining`  | `number` | Quantity still remaining |

#### Example

```lua
local orders = exports['17mov_VendingMachines']:getWholesalerOrders(12)

for _, order in ipairs(orders) do
    print(order.id, order.status)
end
```

***

### `getWholesalerCapacity`

Returns how much of each product can still fit inside a machine.

The returned table is indexed by item name.

#### Usage

```lua
local capacity = exports['17mov_VendingMachines']:getWholesalerCapacity(machineId)
```

#### Parameters

| Parameter   | Type     | Required | Description |
| ----------- | -------- | -------- | ----------- |
| `machineId` | `number` | ✅        | Machine ID  |

#### Returns

```lua
table<string, number> | false
```

For example:

```lua
{
    water = 20,
    cola = 15
}
```

Returns `false` if capacity could not be retrieved.

#### Example

```lua
local capacity = exports['17mov_VendingMachines']:getWholesalerCapacity(12)

if capacity then
    for item, amount in pairs(capacity) do
        print(item, amount)
    end
end
```

***

### `placeWholesalerOrder`

Places a wholesaler order and charges the configured account.

#### Usage

```lua
local result = exports['17mov_VendingMachines']:placeWholesalerOrder(
    machineId,
    cart
)
```

#### Parameters

| Parameter   | Type      | Required | Description       |
| ----------- | --------- | -------- | ----------------- |
| `machineId` | `number`  | ✅        | Machine ID        |
| `cart`      | `table[]` | ✅        | Products to order |

Each cart entry must contain:

| Field      | Type     | Description         |
| ---------- | -------- | ------------------- |
| `item`     | `string` | Inventory item name |
| `quantity` | `number` | Quantity to order   |

#### Returns

| Field     | Type       | Description                  |
| --------- | ---------- | ---------------------------- |
| `success` | `boolean`  | Whether the order was placed |
| `message` | `string?`  | Optional response message    |
| `total`   | `number?`  | Total order value            |
| `orders`  | `table[]?` | Updated order list           |

#### Example

```lua
local result = exports['17mov_VendingMachines']:placeWholesalerOrder(12, {
    { item = 'water', quantity = 10 },
    { item = 'cola', quantity = 5 }
})

if result.success then
    print('Order placed for $' .. result.total)
end
```

***

## Access

### `hasAccess`

Returns whether the player owns or works at any vending machine.

This is useful when you only need a simple yes/no check before opening your own UI or integration.

#### Usage

```lua
local hasAccess = exports['17mov_VendingMachines']:hasAccess()
```

#### Returns

| Type      | Description                                                        |
| --------- | ------------------------------------------------------------------ |
| `boolean` | `true` if the player owns or works at at least one vending machine |

#### Example

```lua
if exports['17mov_VendingMachines']:hasAccess() then
    print('Player can access vending management')
end
```