> ## 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.

# Warehouses

> Create central and express warehouses, activate or deactivate them, and understand how orders, inventory and deliveries use them.

A **warehouse** is a place where supplies are stored and counted. Every box of stock sits in exactly
one warehouse, every order is delivered to a warehouse, and every stock movement says which
warehouse it left or reached. The API calls it a `warehouse` too.

## Central and express warehouses

| Type | Label | Belongs to | Typical use |
| - | - | - | - |
| `central` | **Central** | No location. It serves the whole dental clinic account. | The main store or distribution center that supplies every location. |
| `express` | **Express** | Exactly one location. | The stock kept at a location, including the stock point of a counted room. |

The ownership rule is strict:

* An express warehouse always belongs to one location, chosen when it is created.
* A central warehouse never belongs to a location.
* The type and the location of a warehouse cannot be changed after it is created.

```mermaid theme={null}
flowchart LR
  C["Central warehouse"] -->|supplies| E1["Express warehouse at Clínica Norte"]
  C -->|supplies| E2["Express warehouse at Clínica Sur"]
  E1 --- L1["Location: Clínica Norte"]
  E2 --- L2["Location: Clínica Sur"]
```

## Who can do it

| Action | Who |
| - | - |
| Open **Warehouses** | Every active member of the account |
| Create a warehouse | Owners and admins, or members with `settings.manage` |
| Activate or deactivate a warehouse | Owners and admins, or members with `settings.manage` |
| See and move stock in a warehouse | Members with the inventory permissions and access to that warehouse. See [Use and move stock](/docs/en/inventory/use-and-moves). |
| Decide which warehouses a member works in | Owners and admins, or members with `members.manage` (from **Team**) |

In **Team**, `settings.manage` is shown as **Manage clinic configuration**. A member without it sees
the list in read only mode: no **New warehouse** button and no **Actions** column. See
[Roles and permissions](/docs/en/account/roles-and-permissions).

## Where

Main navigation, **Warehouses** (`console.muveya.com/warehouses`).

## The Warehouses list

The list shows every warehouse of the account, in the order they were created.

| Column | What it shows |
| - | - |
| **Warehouse name** | The name. |
| **Warehouse type** | **Central** or **Express**. |
| **Location** | **All locations** for a central warehouse. For an express warehouse, the name of its location, or **Location unavailable** if that location cannot be shown. |
| **Status** | **Active** or **Inactive**. |
| **Actions** | Managers only: **Activate** or **Deactivate**. |

**Search warehouses** filters by warehouse name, ignoring upper and lower case and accents.

Empty states:

* No warehouses yet: **No warehouses yet**. Managers read **Create a central warehouse or connect an
  express warehouse to a location.**; everyone else reads **Ask your clinic administrator to add a
  warehouse.**
* A search with no match: **No matching results** and **Try a different search.**

<Note>
  This list is not filtered by warehouse access: every member sees every warehouse here. Warehouse
  access decides whose stock a member can see and move in **Inventory**, not what this list shows.
</Note>

## Create a warehouse

<Steps>
  <Step title="Open the form">
    In **Warehouses**, select **New warehouse**. A dialog titled **New warehouse** opens.
  </Step>

  <Step title="Name it">
    Type the **Warehouse name**, for example `Bodega Central Santiago` or `Clínica Norte stock`.
  </Step>

  <Step title="Choose the type">
    In **Warehouse type**, choose **Central** (the default) or **Express**.
  </Step>

  <Step title="Choose the location (express only)">
    If you chose **Express**, a **Location** field appears. Open **Choose a location** and pick the
    location the warehouse belongs to. Only active locations are offered.
  </Step>

  <Step title="Save">
    Select **Save warehouse**. When it finishes, the dialog closes and the warehouse appears in the
    list as **Active**.
  </Step>
</Steps>

Select **Cancel** to close without creating anything.

### Fields and rules

| Field | Required | Rules |
| - | - | - |
| **Warehouse name** | Yes | 1 to 120 characters. Spaces at the start and end are removed. Names are not checked for uniqueness. |
| **Warehouse type** | Yes | **Central** or **Express**. Cannot be changed later. |
| **Location** | Only for **Express** | An active location of this account. Cannot be changed later. A central warehouse never has one. |

* If the account has no active location, the form shows **Create an active location before adding
  an express warehouse.** Create or activate a location first. See [Locations](/docs/en/locations/clinics).
* A new warehouse always starts as **Active**.
* There is no rename, no change of type or location, and no delete. If a warehouse was created
  wrong, create the correct one, move its boxes there (see
  [Use and move stock](/docs/en/inventory/use-and-moves)) and deactivate the old one.

### Warehouses created for you

* **First setup from Home.** The card **Create the first location** creates a location and then opens
  **New warehouse** with the name **Main warehouse** already filled in. When the account already
  has a location but no warehouse, the card **Create a warehouse** opens the same dialog with the same
  name. See [Locations](/docs/en/locations/clinics).
* **Stock point of a counted room.** When you create a room or area with **Counted stock** and leave
  **Create automatically**, muveya creates an express warehouse of that location with the same name
  as the room. It appears in this list like any other express warehouse. See
  [Rooms and areas](/docs/en/locations/destinations).

## Statuses

| Status | Label | Meaning |
| - | - | - |
| `active` | **Active** | The warehouse can take new stock and new orders. |
| `inactive` | **Inactive** | The warehouse and its history are kept, but it takes no new stock and no new orders. |

To change it, select **Deactivate** or **Activate** in the warehouse's row. The change applies
immediately, can be reversed, and has no confirmation step.

### What deactivating a warehouse does

| Area | Effect |
| - | - |
| Receiving stock | The warehouse is no longer offered when receiving. A stale screen that still sends it is refused (`inventory.warehouse_inactive`) and nothing is recorded. |
| Moving boxes into it | It is no longer offered as a destination for a move, and a move into it is refused the same way. |
| Boxes already inside | They stay where they are, with their quantities. They can still be used, or moved out to an active warehouse. |
| New orders | It is no longer offered in **Deliver to warehouse** or **Take stock from**. A stale screen that still sends it is refused with **That warehouse is not active.** |
| Orders already created | Nothing is re-checked. They continue, and a confirmed receipt still credits this warehouse. |
| Stock filters and history | The warehouse still appears in stock filters and in every movement that names it. |
| Counted room | If it is the stock point of a room, the room keeps pointing to it, and boxes can no longer be moved to that room. Consider deactivating the room too. |

Deactivating a warehouse never moves, removes or adjusts stock and writes nothing in the ledger.

## How warehouses are used

### Orders

When you create an order (see [Create and track orders](/docs/en/orders/create-and-track)):

* **Deliver to warehouse** lists the active express warehouses of the location chosen in **Clinic**,
  limited to the warehouses in your warehouse access. If the location has none, the screen says
  **This clinic has no active warehouse yet. Create one in Warehouses first.** If it has some but
  none is in your access, it says **You have no warehouse of this clinic assigned. Ask an
  administrator for access.**
* **Take stock from** offers **Any central warehouse** or one specific active central warehouse.

<Note>
  With **Any central warehouse**, the order names no source warehouse. When stock is reserved for it,
  muveya looks for usable boxes of each supply without limiting the search to one warehouse, so the
  boxes can come from any warehouse that holds that supply, not only central ones. Choose a specific
  central warehouse when the stock must come from it.
</Note>

### Inventory

* Every box belongs to one warehouse. The stock list can be filtered by **Warehouse**.
* Receiving puts new boxes in an active warehouse you have access to. See
  [Receive stock](/docs/en/inventory/receive).
* Moving a box changes its warehouse and records the move in the ledger. See
  [Use and move stock](/docs/en/inventory/use-and-moves).
* Minimum stock and replenishment are set per supply and warehouse. See
  [Replenishment and alerts](/docs/en/inventory/replenishment-and-alerts).
* Counts are done per warehouse. See [Counts](/docs/en/inventory/counts).
* When stock leaves a box toward a room or area, the box's warehouse decides which rooms can be
  chosen: from a central warehouse, the rooms of every location; from an express warehouse, only
  the rooms of its own location. See [Rooms and areas](/docs/en/locations/destinations).

### Deliveries

Boxes reserved for an order are picked and dispatched from the warehouse they are in. When the
receipt is confirmed, accepted boxes are credited to the order's destination warehouse and disputed
boxes go back to the warehouse they came from. See
[Deliveries overview](/docs/en/deliveries/overview) and
[Delivery and receipt](/docs/en/deliveries/delivery-and-receipt).

## How warehouse access narrows what a member sees

Each member has **Warehouse access**: **All warehouses in this account** (including warehouses
created later), **Selected warehouses** or **No warehouse**. It is managed from **Team**; see
[Team](/docs/en/account/team).

| With access to a warehouse, a member can | Without it |
| - | - |
| See its boxes and balances in **Inventory** | The boxes are hidden and behave as if they did not exist |
| Receive into it, move boxes into or out of it, use stock from it (with the matching permission) | These actions are refused |
| Choose it in **Deliver to warehouse** when creating an order | It is not offered |
| See usage recorded from it in **Usage by room** | Those exits are not shown |

A member with **No warehouse** reads **You have no warehouses assigned. Ask an administrator for
access.** in **Inventory**.

<Tip>
  When a member's access lists specific warehouses, new warehouses are not added automatically. This
  includes the stock point muveya creates for a counted room. Open the member in **Team** and add the
  new warehouse, or they will not be able to move boxes into it or use stock from it.
</Tip>

## What the system records

* Creating a warehouse stores its name, type, location (express only) and the `active` status.
  Changing the status updates that same record.
* These changes never write stock movements, and no separate audit entry is written for them.
* Warehouses are never deleted, so movements and boxes that name one keep resolving to it.

## From the API and MCP

* The public API lists warehouses with `GET /v1/warehouses` (scope `clinics:read`). Each item has
  `warehouseId`, `name`, `kind`, `status` and, for express warehouses only, `clinicId`. The API cannot
  create or change warehouses. See [Scopes](/docs/en/api-reference/scopes).
* The MCP tool `clinics.list` lists locations and warehouses. See [MCP tools](/docs/en/mcp/tools).

## What can go wrong

| Message | Why | What to do |
| - | - | - |
| **Enter a value.** | **Warehouse name** is empty or only spaces. | Type a name. |
| **This value is too long.** | The name has more than 120 characters. | Shorten it. |
| **Choose an active location.** | You chose **Express** without a location. | Pick a location in **Location**. |
| **Create an active location before adding an express warehouse.** | The account has no active location. | Create or activate a location in **Locations**. |
| **Review the entered values before trying again.** | muveya refused the data (`common.invalid_request`), or the chosen location no longer exists in this account (`warehouses.clinic_required`). | Reopen the form, choose the location again and retry. |
| **Your account does not have permission for this action.** | You are not an owner or admin and do not have `settings.manage` (`tenants.insufficient_role`). | Ask an owner or admin. |
| **This record is not available in the active dental clinic account.** | The warehouse does not exist in the account you are working in (`warehouses.not_found`). | Check which **Dental clinic** is selected and reload the list. |
| **The record changed or already exists. Review it before trying again.** | You tried to receive into or move a box into a warehouse that was deactivated meanwhile (`inventory.warehouse_inactive`). | Reload the screen and choose an active warehouse. |
| **That warehouse is not active.** | An order named an inactive warehouse (`orders.warehouse_unavailable`). The same message appears when the warehouse is outside your warehouse access or belongs to another location. | Choose another warehouse, or ask an administrator to activate it or give you access. |
| **The active dental clinic account changed. Reload the page before trying again.** | You switched account in another tab (`tenants.context_changed`). | Reload the page. |
| **Could not confirm the operation. Check your connection and review the list before trying again.** | The connection dropped before muveya answered. | Check the list before retrying: the change may already be saved. |
| **Could not complete the request. Please try again.** | Any other failure. | Select **Try again**. If it keeps failing, write to [team@muveya.com](mailto:team@muveya.com). |

## Related pages

<CardGroup cols={2}>
  <Card title="Locations" icon="location-dot" href="/docs/en/locations/clinics">
    The sites that express warehouses belong to.
  </Card>

  <Card title="Rooms and areas" icon="door-open" href="/docs/en/locations/destinations">
    Counted rooms and their stock points.
  </Card>

  <Card title="Use and move stock" icon="right-left" href="/docs/en/inventory/use-and-moves">
    Record usage and move boxes between warehouses.
  </Card>

  <Card title="Team" icon="users" href="/docs/en/account/team">
    Assign warehouse access to each member.
  </Card>
</CardGroup>


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