> ## Documentation Index
> Fetch the complete documentation index at: https://muveya.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Inventory overview

> Understand the Stock screen, box balances and statuses, the immutable stock ledger and who can do what with inventory

muveya counts stock by **box**: a physical container of one supply, with its own printed code, its warehouse, its status and, when the supply tracks them, its lot, serial numbers and expiry date. Every change to a box is written to an append-only **stock ledger**, and the quantities you see are calculated from that ledger. Nothing in the ledger is ever edited or deleted.

This page explains the main inventory screen, how quantities and statuses work, every movement the ledger can record, and which permission each action needs.

## Open the Stock screen

Select **Inventory** in the main navigation. The screen that opens is titled **Stock** ("Boxes on hand across the warehouses you can see."). You can also go straight to `console.muveya.com/inventory`.

The **Inventory** entry is shown to every member, but the list only loads for members with the `inventory.read` permission. Without it, the screen shows **Your account does not have permission for this action.**

### What the list shows

Each row is one box.

| Column | What it shows |
| - | - |
| **Supply** | The supply's name and SKU, for example `Nitrile gloves M · GLV-NIT-M`. Select it to open the box. |
| **Warehouse** | The warehouse where the box is now. |
| **On hand** | Units physically in the box, with the supply's unit, for example `100 × Unit`. |
| **Reserved** | Units of that box held for approved orders. |
| **Available** | On hand minus reserved: what is still free. |

The list includes boxes in every status, so a box that was used up can still appear with `0` on hand. The box code is not a column: open the box to see it.

### Filter the list

| Filter | Options |
| - | - |
| **Supply** | **All supplies**, or any supply by name and SKU (active or not, because stock can still hold a retired supply). |
| **Warehouse** | **All warehouses**, or one warehouse by name (active or not). |

You only ever see boxes in the warehouses your team access reaches. The list shows up to 50 boxes, oldest first, and has no next page: when you expect more, narrow it with the filters.

### States and messages

| Message | Meaning |
| - | - |
| **Loading stock…** | The list is loading. |
| **No boxes match this view.** | No box matches the filters in your warehouses. |
| **You have no warehouses assigned. Ask an administrator for access.** | Your team access lists no warehouse, so nothing can appear. An administrator changes it in [Team](/docs/en/account/team). |
| **Your account does not have permission for this action.** | You do not have `inventory.read`. |

### Shortcuts at the top of the screen

| Link | Opens | Guide |
| - | - | - |
| **Receive** | The receiving screen. Shown only to members who can receive. | [Receive stock](/docs/en/inventory/receive) |
| **Scan a code** | The box finder. | [Boxes and labels](/docs/en/inventory/boxes) |
| **Usage by room** | What left stock toward each room or area. | [Record use and move boxes](/docs/en/inventory/use-and-moves) |
| **Replenishment** | Supplies below their minimum. | [Replenishment and alerts](/docs/en/inventory/replenishment-and-alerts) |
| **Stock alerts** | Low stock and expiry alerts. | [Replenishment and alerts](/docs/en/inventory/replenishment-and-alerts) |
| **Lot recall** | Every box of a lot. | [Lot recall](/docs/en/inventory/lot-recall) |
| **Counts** | Counts due, in progress and their differences. | [Counts](/docs/en/inventory/counts) |
| **Stock corrections** | Corrections waiting for approval. | [Corrections](/docs/en/inventory/corrections) |

## Balances: on hand, reserved and available

Every box has two counters, both calculated from the ledger:

* **On hand** (`onHand`): the units in the box. Receiving adds to it; using, dispatching and loss corrections subtract from it. It can never go below zero.
* **Reserved** (`reserved`): units of the box held for approved orders. Reserving never changes on hand.
* **Available** (`available`): `onHand` minus `reserved`. Order allocation only reserves available units, and separating part of a box only takes available units.

Quantities are always in the supply's base unit (the unit set in the [catalog](/docs/en/catalog/items)), shown in your language, for example `24 × Box`. The unit is locked when the supply is activated in the catalog (a receipt also locks it if it was not locked yet), and every box keeps the unit it was received under. A box whose stored unit cannot be confirmed shows its numbers without a unit and the note **The unit of this box needs review. Its quantities are shown without a unit until someone checks it.**

## Box statuses

| Status | Label | What it means | What the box accepts |
| - | - | - | - |
| `active` | **Active** | In use in its warehouse. | Use, moves, separation, corrections, counts, reservations for orders, and being taken out of use. |
| `quarantine` | **Quarantined** | Held apart for review or a recall. | No use, no moves, never picked for an order. It can still be disposed of, but the console has no button for that. |
| `expired` | **Expired** | Marked as expired by a person. | No use, no moves, never picked. It can still be disposed of, but the console has no button for that. |
| `depleted` | **Used up** | Its on hand reached zero through use or a loss correction. | Nothing. Its history stays readable. |
| `disposed` | **Disposed** | Discarded. Final status. | Nothing. |
| `in_transit` | **In transit** | Dispatched for an order and not yet received at the destination. | Nothing until the receipt is confirmed. |

```mermaid theme={null}
stateDiagram-v2
    state "Active" as Active
    state "Quarantined" as Quarantined
    state "Expired" as Expired
    state "Used up" as UsedUp
    state "Disposed" as Disposed
    state "In transit" as InTransit
    [*] --> Active: Received
    Active --> UsedUp: On hand reaches zero
    Active --> Quarantined: Quarantine or lot recall
    Active --> Expired: Mark as expired
    Active --> Disposed: Dispose
    Quarantined --> Disposed: Dispose
    Expired --> Disposed: Dispose
    Active --> InTransit: Order dispatched
    InTransit --> Active: Receipt accepted or disputed
    InTransit --> Quarantined: Receipt disputed and held
```

<Warning>
  A box does not change status by itself when its expiry date passes. It stays **Active**, but from the day after its expiry date (UTC) it can no longer be used, moved or separated, and orders never reserve it. Take it out of use with **Mark as expired**, as described in [Boxes and labels](/docs/en/inventory/boxes).
</Warning>

## The stock ledger

The ledger is the only source of truth for stock. Each movement records its type, the box, the supply, the signed change to on hand (and to reserved when it applies), who recorded it, when it happened (server clock), the warehouse it left or entered and, when given, a reason. A mistake is fixed with a new, compensating movement, never by editing an old one. You read a box's movements on the box screen; see [Boxes and labels](/docs/en/inventory/boxes).

| Type | Label on the box | Created when | On hand | Reserved |
| - | - | - | - | - |
| `receive` | **Received** | Someone receives a delivery ([Receive stock](/docs/en/inventory/receive) or [WhatsApp](/docs/en/whatsapp/operations)). Also when a box dispatched for an order is accepted at the destination warehouse. | Adds | No change |
| `reserve` | **Reserved** | An approved order is allocated and the system holds units of a box for it. Also when picking separates the order's units into a new container. | No change | Adds |
| `release` | **Released** | A reservation is freed: an allocation is undone, the system clears a stuck allocation, or picking moves the order's units to a new container. | No change | Subtracts |
| `pick` | **Picked** | A reserved box is scanned while [picking](/docs/en/deliveries/picking) an order. | No change | No change |
| `dispatch` | **Dispatched** | The order is dispatched. The box becomes **In transit**. | Subtracts | Subtracts |
| `transfer_out` | **Moved out** | A whole box is moved to another warehouse (recorded on the origin). | No change | No change |
| `transfer_in` | **Moved in** | The same move, recorded on the destination. | No change | No change |
| `split_out` | **Separated out** | Part of a box is separated into a new container (recorded on the original box). | Subtracts | No change |
| `split_in` | **Separated in** | The same separation, recorded on the new container. | Adds | No change |
| `consume` | **Used**, or **Delivered** when it was handed to a room | Someone records use or an exit from a box ([Record use and move boxes](/docs/en/inventory/use-and-moves) or WhatsApp). | Subtracts | No change |
| `return` | **Returned** | A dispatched box whose receipt was disputed goes back to its origin warehouse, active or quarantined ([Delivery and receipt](/docs/en/deliveries/delivery-and-receipt)). | Adds | No change |
| `adjust_gain` | **Correction (gain)** | A correction or a count finds more than the record says ([Corrections](/docs/en/inventory/corrections), [Counts](/docs/en/inventory/counts)). | Adds | No change |
| `adjust_loss` | **Correction (loss)** | A correction or a count finds less than the record says. At zero the box becomes **Used up**. | Subtracts | No change |
| `expire` | **Expired** | Someone marks the box as expired. | No change | No change |
| `quarantine` | **Quarantined** | Someone quarantines the box, or a [lot recall](/docs/en/inventory/lot-recall) holds it. | No change | No change |
| `dispose` | **Disposed** | Someone disposes of the box. | No change | No change |

A consumption that uses up the last unit also sets the box to **Used up**. Moves, status changes and picks carry a change of `0`: the box keeps its units, only its place or status changes.

## FEFO and FIFO

When an approved order is allocated, muveya reserves units box by box in a fixed order:

* **FEFO** (first expiry, first out) applies when any eligible box of the supply has an expiry date. Boxes with the earliest expiry go first; boxes without an expiry go last; ties are broken by reception date.
* **FIFO** (first in, first out) applies otherwise. The oldest reception goes first.

Only **Active** boxes whose expiry date has not passed, in the source warehouse, with the unit the order expects, are eligible, and only their available units are reserved. The order is calculated by the server and is the same every time. When you use or move a box yourself, you choose the box by scanning it; the console does not suggest one. There is no console action to override the order for an allocation.

## Permissions

Inventory permissions are granted one by one in [Team](/docs/en/account/team). No role grants them automatically: an owner or administrator also needs them to see or change stock. See [Roles and permissions](/docs/en/account/roles-and-permissions).

| Permission | Label in Team | What it allows |
| - | - | - |
| `inventory.read` | **View inventory** | See the Stock list, open and scan boxes, read movements, usage by room, lot recall, replenishment, alerts, counts and corrections. Needed by every inventory screen except **Receive**. |
| `inventory.receive` | **Receive deliveries** | Receive stock into a warehouse. |
| `inventory.consume` | **Record usage** | Record use or an exit from a box, and attribute an earlier exit later. |
| `inventory.transfer` | **Move boxes between warehouses** | Move a whole box to another warehouse, and separate part of a box into a new container. |
| `inventory.adjust` | **Adjust and count stock** | Corrections, counts, minimums, deciding corrections, taking a box out of use and quarantining a lot. It **includes** `inventory.receive`, `inventory.consume` and `inventory.transfer`. |

<Note>
  `inventory.adjust` does not include `inventory.read`. Grant both to someone who must see what they correct.
</Note>

Every permission applies only inside the member's **warehouse access** (all warehouses, or a specific list). A box in a warehouse outside that access behaves exactly as if it did not exist: scanning its code says the box was not found.

Moving a box, taking a box out of use and quarantining a lot are marked as sensitive actions. In the current release a second factor is optional and does not block them; see [Account security](/docs/en/account/security).

## Map of the inventory screens

| Screen | Path | What you do there | Guide |
| - | - | - | - |
| **Stock** | `/inventory` | Browse boxes and balances. | This page |
| **Receive** | `/inventory/receive` | Receive a delivery into a new box. | [Receive stock](/docs/en/inventory/receive) |
| **Scan** | `/inventory/scan` | Find a box by its code. | [Boxes and labels](/docs/en/inventory/boxes) |
| Box (titled with its code) | `/inventory/boxes/:boxId` | See a box, print its label, use, move, separate, correct or take it out of use. | [Boxes and labels](/docs/en/inventory/boxes) |
| **Usage by room** | `/inventory/usage` | Review exits by room or area and attribute them. | [Record use and move boxes](/docs/en/inventory/use-and-moves) |
| **Lot recall** | `/inventory/lots` | Find every box of a lot and quarantine it. | [Lot recall](/docs/en/inventory/lot-recall) |
| **Replenishment** | `/inventory/replenishment` | Supplies below their minimum. | [Replenishment and alerts](/docs/en/inventory/replenishment-and-alerts) |
| **Minimum per warehouse** | `/inventory/replenishment/policy` | Set minimums and approval thresholds. | [Replenishment and alerts](/docs/en/inventory/replenishment-and-alerts) |
| **Stock alerts** | `/inventory/alerts` | Low stock and expiry alerts. | [Replenishment and alerts](/docs/en/inventory/replenishment-and-alerts) |
| **Counts** | `/inventory/counts` | Counts due, in progress and differences. | [Counts](/docs/en/inventory/counts) |
| **Count a supply** | `/inventory/count` | Count the boxes of one supply in one warehouse. | [Counts](/docs/en/inventory/counts) |
| **Count of** a warehouse | `/inventory/count-campaigns/:campaignId` | Follow a warehouse count campaign. | [Counts](/docs/en/inventory/counts) |
| **Stock corrections** | `/inventory/approvals` | Approve, reject or withdraw corrections. | [Corrections](/docs/en/inventory/corrections) |

**Replenishment** and **Stock corrections** also appear in the main navigation.

## Read inventory from the API or MCP

The same balances and ledger are readable with an API key that has the `inventory:read` scope: `GET /v1/inventory/balances`, `GET /v1/inventory/boxes/{boxId}`, `GET /v1/inventory/boxes/{boxId}/balance` and `GET /v1/inventory/boxes/{boxId}/movements`. They are read-only. See the [API reference](/docs/en/api-reference/introduction). Through MCP, the `inventory.check` tool returns on hand, reserved and available for one supply; see [MCP tools](/docs/en/mcp/tools).

## Related pages

<CardGroup cols={2}>
  <Card title="Receive stock" icon="truck-ramp-box" href="/docs/en/inventory/receive">
    Turn a delivery into labeled boxes.
  </Card>

  <Card title="Boxes and labels" icon="box-open" href="/docs/en/inventory/boxes">
    Scan, inspect, separate, label and retire a box.
  </Card>

  <Card title="Record use and move boxes" icon="arrow-right-arrow-left" href="/docs/en/inventory/use-and-moves">
    Exits, rooms, attribution and moves.
  </Card>

  <Card title="Warehouses" icon="warehouse" href="/docs/en/locations/warehouses">
    Central and express warehouses.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.