Skip to main content
The custody detail tells the whole story of one order’s delivery: which boxes were reserved, who picked and dispatched them, who confirmed the handoff, what the destination accepted or disputed, and who closed the order. Use it to follow a delivery day to day and to answer audit questions or disputes later.

​
Who can see it

  • Permission fulfillment.read (View fulfillment).
  • The order’s location in your Location access.
Without the permission the screen says “You cannot view deliveries. Ask your clinic’s administrator for the permission.” An order outside your locations, or one that has no custody record yet, answers “This delivery does not exist or you cannot see it.”

​
Where

  • In Deliveries, open To close or Delivery problems and select the order number.
  • On the order’s page, Follow the delivery (shown to members with any custody permission). See Create and track orders.
  • After confirming a reception, the link under the confirmation message.
  • On the pick screen of an order that is no longer being prepared, the Tracking order #1042 link.
  • Direct path: console.muveya.com/fulfillment/:orderId.

​
What the screen shows

The screen is titled Tracking order #1042, with Back to deliveries to return to the queue.

​
Facts and next step

Below the facts, the screen offers the next step when it is yours to take: For closing, see Close the order.

​
Boxes

Boxes lists every box assigned to the order. On a phone, each box is shown as a labeled card. When a box was separated at pick time, the list shows the new container, not the original box. If no box is assigned, the screen says “No boxes are assigned to this order.”

​
History

History lists what happened, one entry per event, each with the person and the date and time in your browser’s format. People are named by their team name; the signed-in person reads as You, actions muveya took by itself as Muveya (automatic), and people who left the team as Former team member. Stock movements come first, oldest first. Each reads “movement · box code · quantity change”, for example “Dispatched · BX-000123 · -10”. Movements that do not change the quantity on hand omit the number, for example “Picked · BX-000123”. Custody records follow the movements: If nothing has happened yet, the section says “Nothing has happened yet.”
Movements made on the original box of a separation show Box no longer in the ledger in place of its code, because the Boxes list only names the new container. Open the original box from Boxes to see its own history.

​
Use it for audits and disputes

A typical dispute review:
1

Confirm the chain of people

Check that the person who picked, the person who dispatched and the person who confirmed the delivery are the ones you expect on the origin side, and that the reception was made by the destination side.
2

Compare delivered and received

Every box in the delivery must appear once in the reception, as accepted or disputed.
3

Follow each disputed box

Find its Returned movement and its current Box state. If it came back in quarantine, decide what to do with it from its box page.
4

Check the lot if needed

If the problem may affect a whole lot, continue in Lot recall.

​
What the screen does not show

  • The Evidence of the problem text typed at reception. It is stored but not shown on the console or returned by the API today.
  • The per-box notes of a dispute and the quarantine choice. The API returns both.
  • The carrier reference typed at dispatch. GET /v1/fulfillments returns it as carrierRef.
  • The audit log. There is no audit log screen on the console today.
  • An export. To keep custody histories outside muveya, read them from the API.
The records are append-only: nothing in this history can be edited or deleted. A disputed box is corrected by a new Returned movement, never by changing the Dispatched one.

​
Read it from the API

The operation GET /v1/fulfillments/{orderId} returns the same custody history for integrations and reporting.
  • Authentication: an API key (mvy_test_...) in the Authorization: Bearer header. API keys are not created from the console today; see Authentication.
  • Scope: fulfillment:read. See Scopes.
  • Reach: the key’s whole dental clinic account. There is no location filter on a key.
  • Read-only: custody steps (pick, dispatch, delivery, reception, close) cannot be performed through the API or MCP.

​
Response

​
string
required
The order id.
​
string
required
The custody status: allocating, allocated, picking, dispatched, delivered, exception, received, partially_fulfilled or closed.
​
object[]
required
The order’s stock movements, oldest first. Each has movementId, type, boxId, catalogItemId, quantityDelta, actorId, occurredAt and recordedAt, and when they apply reservedDelta, fromWarehouseId, toWarehouseId, reasonCode, secondActorId, idempotencyKey and correlationId.
​
object
Present once the delivery was confirmed: actorUserId, deliveredAt, boxIds and, for a delivery problem, exception with reason and optional note.
​
object
Present once the reception was confirmed: actorUserId, receivedAt, acceptedBoxIds and disputed, a list of boxId, reason, quarantine and optional note.
​
object
Present once the order was closed: actorUserId and closedAt.
Example response
How the API differs from the screen:
  • It returns ids, not names or box codes. Read a box’s code and state with GET /v1/inventory/boxes/{boxId} (scope inventory:read), and a supply with GET /v1/catalog/items/{itemId} (scope catalog:read).
  • actorId and actorUserId are member ids. Actions muveya took by itself carry system:fulfillment.
  • The status allocating can appear briefly while the reservation runs; the console shows it as Reserving stock.
  • It answers 404 when the order does not exist, belongs to another dental clinic account, or has no custody record yet (an approved order whose stock is not reserved).
  • Other answers: 401 for a missing or invalid key, 403 when the key lacks fulfillment:read, 429 when the key exceeds its rate limit. See Errors and Rate limits.
To list custody records, use GET /v1/fulfillments with the optional status filter, limit (1 to 200, default 50) and cursor. Each item has orderId, status, createdAt, updatedAt and, when they apply, sourceWarehouseId, dispatchedAt and carrierRef. See Pagination.
The MCP tool fulfillment.get_pick_list needs the fulfillment.pick permission, which the current read-only OAuth scope set does not grant, so it is refused on the /mcp endpoint today. See MCP tools.

Deliveries overview

Lifecycle, permissions and parties.

Delivery and receipt

How the delivery, reception and closure records are made.

Boxes

The full history of a single box.

API scopes

Which scope each read needs.