> ## 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.
# Deliveries overview
> Understand the Deliveries screen, the custody steps from an approved order to a closed one, and who may take each step.
A **delivery** is the physical journey of an approved order: muveya reserves boxes of stock for it, someone picks and dispatches them from the source warehouse, someone confirms the handoff, and the destination receives and closes the order. muveya records every step as custody of whole boxes, so you can always say which box left which warehouse, who handed it over and who received it.
In the API and in the code this process is called *fulfillment*. In the console it lives under **Deliveries**.
## Where to find it
* **Deliveries** in the main navigation opens `console.muveya.com/fulfillment`. The item appears only to members who hold at least one custody permission (see [Permissions for each step](#permissions-for-each-step)).
* **Home** shows the cards **Orders to prepare**, **Deliveries to confirm**, **Orders to receive** and **Orders to close** when something waits for you. Each card opens **Deliveries**.
* On an order's page, **Follow the delivery** opens the custody detail of that order. See [Create and track orders](/docs/en/orders/create-and-track).
muveya does not send email or WhatsApp messages when a delivery changes step. Check **Home** and **Deliveries** to see what waits for you.
## The Deliveries screen
The screen is titled **Deliveries** ("Orders of your clinics to prepare, deliver, receive or close.") and shows one section per custody step you take part in. You only see the sections your permissions allow.
| Section | Orders listed (status) | Shown to members with | The order link opens |
| - | - | - | - |
| **To prepare** | `allocated`, `picking` | `fulfillment.pick` or `fulfillment.dispatch` | The pick screen, `/fulfillment/:orderId/pick` |
| **To deliver** | `dispatched` | `delivery.confirm` | The delivery screen, `/fulfillment/:orderId/delivery` |
| **To receive** | `delivered` | `receipt.confirm` | The receipt screen, `/fulfillment/:orderId/receipt` |
| **To close** | `received`, `partially_fulfilled` | `fulfillment.close` | The custody detail, `/fulfillment/:orderId` |
| **Delivery problems** | `exception` | `fulfillment.read` | The custody detail, `/fulfillment/:orderId` |
Each section is a table with these columns:
| Column | What it shows |
| - | - |
| **Order** | The order number, for example `#1042`. Select it to open the step. |
| **Status** | The current order status, with its console label (see the table below). |
| **Clinic** | The location the order belongs to. |
| **Deliver to** | The destination warehouse. |
Rules of the list:
* You see the orders of the locations in your **Location access**. With **All locations in this account** you see every location's orders.
* Each section shows up to 50 orders, newest first. When there are more, the section says "Showing the first 50. Finish these to see the rest."
* An empty section says "Nothing here right now."
* If you hold no custody permission, the screen says "You do not take part in deliveries. Ask your clinic's administrator if you should prepare, deliver or receive orders."
## The custody lifecycle
An order enters custody when it is approved, either by a person in [Order approvals](/docs/en/orders/approvals) or automatically by the [approval policy](/docs/en/orders/approval-policy). From there the custody record moves through these statuses:
```mermaid theme={null}
stateDiagram-v2
approved: Order approved
allocating: Reserving stock
allocated: Stock reserved
picking: Being prepared
dispatched: Dispatched
delivered: Delivered
exception: Delivery problem
received: Received
partially_fulfilled: Partially received
closed: Closed
[*] --> approved
approved --> allocating: automatic reservation
allocating --> allocated: every line reserved
allocating --> approved: not enough stock, nothing kept
allocated --> picking: first box scanned
picking --> dispatched: dispatch
dispatched --> delivered: delivery confirmed
dispatched --> exception: delivery problem reported
delivered --> received: every box accepted
delivered --> partially_fulfilled: at least one box disputed
received --> closed: close
partially_fulfilled --> closed: close
closed --> [*]
```
| Status | Console label | What it means | Next step |
| - | - | - | - |
| `allocating` | **Reserving stock** | muveya is reserving boxes for the order. Only the custody record has this status: the order itself still shows **Approved**. | Automatic. |
| `allocated` | **Stock reserved** | Every order line has boxes reserved. | Pick the boxes. |
| `picking` | **Being prepared** | At least one reserved box was scanned. | Pick the rest and dispatch. |
| `dispatched` | **Dispatched** | The picked boxes left the source warehouse. They are **In transit**. | Confirm the delivery. |
| `delivered` | **Delivered** | The handoff at the destination was confirmed. | Confirm the reception. |
| `exception` | **Delivery problem** | A problem was reported instead of a clean delivery. The order stops here. | None on the console today (see [Delivery problems](/docs/en/deliveries/delivery-and-receipt#when-a-delivery-problem-is-reported)). |
| `received` | **Received** | The destination accepted every box. | Close the order. |
| `partially_fulfilled` | **Partially received** | The destination disputed at least one box, which went back to the origin. | Close the order. |
| `closed` | **Closed** | Custody is finished. | None. |
The order's own status follows the same steps (`allocated`, `picking`, `dispatched`, `delivered`, `exception`, `received`, `partially_fulfilled`, `closed`), so the [Orders](/docs/en/orders/create-and-track) screen and **Deliveries** always agree.
### Step 1: automatic stock reservation
Nobody reserves stock by hand. When an order is approved, muveya reserves it on its own:
1. For each order line it looks at the usable boxes of that supply: boxes in state **Active**, not past their expiry date, and measured in the same unit as the order line.
2. If the order names a source warehouse (**Take stock from** on the order), only that warehouse's boxes count.
3. It ranks the boxes **FEFO** (first expiry, first out: the earliest expiry date first, boxes without an expiry date last, then the oldest reception) whenever at least one candidate box has an expiry date, and **FIFO** (the oldest reception first) otherwise.
4. It reserves from the first box, then the next, until the line's quantity is covered. One line can draw from several boxes, and a box can be reserved for only part of its content.
5. The reservation is all or nothing. If any line cannot be covered, muveya releases everything it reserved for that order and leaves the order in **Approved**.
These reservations appear in the order's history as **Reserved** movements made by **Muveya (automatic)**.
When the order was left on **Any central warehouse**, the reservation is not limited to one warehouse: muveya ranks every usable box of that supply in the dental clinic account. Before picking, check the **Take from** column of the pick list to see where each box really is.
If an approved order could not be reserved:
* It does not appear in **Deliveries**, and its order page keeps saying "The order is moving to its next step. This screen refreshes by itself in a few seconds."
* muveya tries again each time another order of the same dental clinic account is approved. There is no retry button on the console today.
* Receive or move the missing stock ([Receive stock](/docs/en/inventory/receive), [Use and move stock](/docs/en/inventory/use-and-moves)). If the order still stays in **Approved**, write to [team@muveya.com](mailto:team@muveya.com) with the order number.
## Whole-box custody
muveya moves custody one **whole box** at a time. A box (any labeled container with a code such as `BX-000123`) is picked, dispatched, delivered and received as one unit. What that means in practice:
* **A box sized to the order** travels as it is.
* **A box that holds more than the order needs** is split when you scan it: muveya separates exactly the reserved quantity into a new container with its own label, and only that new container travels. The rest stays in the original box, in its warehouse. See [Separating a box at pick time](/docs/en/deliveries/picking#separating-a-box-at-pick-time).
* **Reception is per box.** The destination accepts or disputes each whole box. There is no way to accept part of a box. If a box arrived with fewer units than its label says, see [Partial quantities](/docs/en/deliveries/delivery-and-receipt#partial-quantities).
* **While a box travels** it is **In transit**. It no longer counts in the source warehouse and does not count in the destination until it is accepted.
For how boxes are labeled and tracked in general, see [Boxes](/docs/en/inventory/boxes).
## Permissions for each step
Each custody step has its own permission. Permissions are never inherited from a role name: a member can do a step only if an administrator granted that exact permission on the **Team** screen. See [Roles and permissions](/docs/en/account/roles-and-permissions).
| Permission | Label on the Team screen | What it allows | Side |
| - | - | - | - |
| `fulfillment.read` | **View fulfillment** | Open the custody detail and see **Delivery problems**. | Either |
| `fulfillment.pick` | **Prepare orders** | Open the pick screen, see the pick list and scan boxes. | Origin |
| `fulfillment.dispatch` | **Dispatch orders** | Dispatch the picked boxes. | Origin |
| `delivery.confirm` | **Confirm delivery** | Confirm the handoff or report a delivery problem. | Origin |
| `receipt.confirm` | **Confirm receipt** | Accept or dispute the delivered boxes. | Destination |
| `fulfillment.close` | **Close fulfillment** | Close a received or partially received order. | Destination |
Some console screens need two permissions together:
* **Dispatching** happens on the pick screen, which opens only with `fulfillment.pick`. A member with `fulfillment.dispatch` alone sees the order under **To prepare** but cannot dispatch it from the console.
* **Receiving** box by box needs `receipt.confirm` and `fulfillment.read`. Without `fulfillment.read` the receipt screen says "To receive box by box you also need permission to view deliveries. Ask your clinic's administrator."
* **Closing** is done on the custody detail, which needs `fulfillment.read`. A member with `fulfillment.close` alone cannot reach the **Close order** button.
Custody steps never ask for authenticator (TOTP) verification.
## Origin party and destination party
Every delivery has two sides, and muveya checks each step against the side it belongs to.
* **Origin party**: the people who prepare, dispatch and hand over the boxes. muveya checks their **Location access** against the location that owns the **source warehouse**. When the source is a central warehouse, or the order named no source, it checks the order's location instead.
* **Destination party**: the people who receive and close. muveya checks their **Location access** against the location that owns the **destination warehouse**, or the order's location when the destination is a central warehouse.
Additional rules:
* **Picking and viewing** are checked against the order's location.
* **Warehouse access matters for the origin.** To scan a box, your **Warehouse access** must include the warehouse the box is in; a box outside it is treated as "not reserved for this order". Dispatching also needs access to the warehouse of each box.
* **Separation of duties between locations.** When the source and destination warehouses belong to two different locations, a member whose **Location access** includes the origin location cannot receive or close that order. muveya answers "Your account does not have permission for this action." Members with **All locations in this account** are not blocked by this rule; their permissions alone decide.
* An order outside your locations behaves as if it did not exist: the custody detail and receipt screens say "This delivery does not exist or you cannot see it.", and the pick and delivery screens say "This record is not available in the active dental clinic account."
## What the system records
| Step | Stock movements in the ledger | Order status after | Audit record |
| - | - | - | - |
| Reservation | **Reserved** on each box (no change to quantity on hand) | `allocated` | `fulfillment.allocated` |
| Pick | **Picked** on each box (no change to quantity); **Separated out** and **Separated in** when a box is split | `picking` | `fulfillment.picked` |
| Dispatch | **Dispatched** on each box (quantity leaves the source warehouse) | `dispatched` | `fulfillment.dispatched` |
| Delivery | None: the boxes stay **In transit** | `delivered` or `exception` | `fulfillment.delivered` or `fulfillment.delivery_exception` |
| Reception | **Received** at the destination for each accepted box; **Returned** at the origin for each disputed box | `received` or `partially_fulfilled` | `fulfillment.received` or `fulfillment.received.disputed` |
| Close | None | `closed` | `fulfillment.closed` |
The ledger is append-only: a disputed box is not erased from the dispatch, it gets a new **Returned** movement. The custody detail shows all of this for one order; see [Custody history](/docs/en/deliveries/custody-history). There is no audit log screen on the console today.
Every custody action is safe to repeat. Dispatching, confirming a delivery, confirming a reception or closing an order a second time does not change anything: the screen answers that it was already recorded.
## Related pages
Scan the reserved boxes, split larger boxes and dispatch the order.
Confirm the handoff, receive or dispute each box, and close the order.
Review who did what and when, for audits and disputes.
How an order gets approved and enters custody.
Box codes, states and the movements of each box.
Grant the custody permissions and location access.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.