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

# Catalog items

> Search, create and maintain the supplies of your dental clinic, and understand the draft, active and inactive statuses.

The catalog is the closed list of supplies your dental clinic works with. Every order line, stock box and consumption record points to a supply in this list, so a supply has to exist here before anyone can order, receive or use it. The console calls each catalog item a *supply*; the API and the code call it an item.

## Who can do it

| Action | Permission | Notes |
| - | - | - |
| See the list and open a supply | `catalog.read` | Every role (Owner, Administrator, Member) includes it. |
| Create a supply, edit it, activate or deactivate it | `catalog.manage` | Owners and Administrators have it through their role. A Member needs it granted as **Manage the catalog**. |
| See costs in the list and on the supply | `catalog.cost.read` | No role includes it, not even Owner. It must be granted as **View supply costs**. See [Costs](/docs/en/catalog/costs). |

Permissions are assigned per member on the **Team** screen. See [Roles and permissions](/docs/en/account/roles-and-permissions).

## Where

Open **Catalog** in the main navigation. The module has three item screens:

| Screen | Path | What it is for |
| - | - | - |
| **Catalog** | `/catalog` | Search, filter and open supplies. |
| **New supply** | `/catalog/items/new` | Create a supply. |
| Supply detail | `/catalog/items/:itemId` | Edit a supply, change its status, manage its presentations and its cost. |

## The catalog list

The **Catalog** screen (**Organize the supplies used by your dental clinic.**) shows:

* **New supply**, in the page header, if you hold `catalog.manage`.
* A search box, **Search by SKU or name**. It matches any part of the SKU or the name, ignoring letter case and accents, so `anestesico` finds "Anestésico local".
* Links to **Categories**, and, if you hold `catalog.manage`, **Import CSV** and **Export CSV**. See [Categories](/docs/en/catalog/categories) and [Import and export](/docs/en/catalog/import-export).
* Two filters: **Category** (default **All categories**) and **Status** (default **All statuses**, then **Draft**, **Active**, **Inactive**). **Clear filters** resets the search and both filters.

The table has the columns **SKU**, **Supply name**, **Category**, **Unit** and **Status**, plus **Cost** when you hold `catalog.cost.read`. Click the supply name to open it. Supplies are listed in the order they were created, oldest first, 50 per page, with **Previous** and **Next** below the table and a counter of the rows shown out of the total.

| What you see | Meaning |
| - | - |
| **No supplies yet** | The catalog is empty. Managers read **Create a category and add the first supply to your catalog.**; everyone else reads **An administrator can add supplies to this catalog.** |
| **No matching supplies** | Nothing matches the search or filters. **Try a different search.** |
| **Category unavailable** | The supply points to a category the screen could not find. Open the supply and choose a category. |

## Create a supply

<Steps>
  <Step title="Have a category ready">
    Every supply belongs to a category. If none exists, the form says **Create a category before adding supplies.** You can create one from [Categories](/docs/en/catalog/categories) or with **New category** inside the form, which selects the new category for you.
  </Step>

  <Step title="Open the form">
    In **Catalog**, click **New supply**. The page **New supply** opens with **Define how this supply is identified and tracked.**
  </Step>

  <Step title="Fill in the supply information">
    Under **Supply information**, enter **SKU**, **Supply name**, **Category**, **Unit**, **Packaging**, **Criticality** and **Description**. The rules for each field are in the table below.
  </Step>

  <Step title="Choose the tracking requirements">
    Under **Tracking requirements** (**These choices define the information required when registering stock.**), tick **Track lots**, **Track serial numbers**, **Track expiration dates** and **High-value supply** as needed. All four start unticked.
  </Step>

  <Step title="Save">
    Click **Create supply**. The console opens the new supply's detail page. The supply starts as **Draft**: activate it when it is ready to be ordered.
  </Step>
</Steps>

<Note>
  The creation form has no cost field. Record the cost on the supply's detail page after creating it, or include it in a CSV import. See [Costs](/docs/en/catalog/costs).
</Note>

## Fields and validation

| Field (console label) | Required | Rules | Can change later |
| - | - | - | - |
| `sku` (**SKU**) | Yes | 1 to 64 characters. Letters, digits, dots, underscores, slashes and hyphens only, no spaces. Unique in your dental clinic, compared exactly (`GLV-NIT-M` and `glv-nit-m` are different codes). | Never. |
| `name` (**Supply name**) | Yes | Up to 200 characters, not only spaces. | Yes. |
| `description` (**Description**) | No | Up to 2,000 characters. | Yes. |
| `categoryId` (**Category**) | Yes | A category of your own dental clinic. | Yes. |
| `unitOfMeasure` (**Unit**) | Yes | One of the units below. | Only until the unit is fixed. See [The unit becomes fixed](#the-unit-becomes-fixed). |
| `packaging` (**Packaging**) | No | Free text up to 200 characters, for example "Box of 100". Descriptive only: it never changes a quantity. | Yes. |
| `criticality` (**Criticality**) | Yes | `low` (**Low**), `medium` (**Medium**) or `high` (**High**). | Yes. |
| `tracksLot` (**Track lots**) | No | Off by default. | Yes. |
| `tracksSerial` (**Track serial numbers**) | No | Off by default. | Yes. |
| `tracksExpiry` (**Track expiration dates**) | No | Off by default. | Yes. |
| `highValue` (**High-value supply**) | No | Off by default. | Yes. |

The **Unit** is the base unit the supply is counted in everywhere: stock, orders, consumption and presentations. The allowed values are:

| Code | Label | Code | Label |
| - | - | - | - |
| `unit` | **Unit** | `liter` | **Liter** |
| `box` | **Box** | `gram` | **Gram** |
| `pack` | **Pack** | `kilogram` | **Kilogram** |
| `bottle` | **Bottle** | `pair` | **Pair** |
| `ampoule` | **Ampoule** | `kit` | **Kit** |
| `milliliter` | **Milliliter** | | |

<Tip>
  The free-text **Packaging** field is not a presentation. To say that a box contains 100 units, so that receiving 3 boxes adds 300 units, add a presentation on the supply. See [Presentations and codes](/docs/en/catalog/presentations-and-codes).
</Tip>

### What the tracking choices do

| Choice | Effect |
| - | - |
| **Track lots** | Every stock reception of the supply must include a lot number. |
| **Track serial numbers** | Every reception must include one serial number per unit received, with no repeats, and a serial already received cannot be received again. |
| **Track expiration dates** | Every reception must include an expiration date that is not in the past. |
| **High-value supply** | Order approval rules can target orders that contain high-value supplies (**Only orders with high-value supplies**), and every stock correction of the supply needs a second person to approve it. |

A change to these choices applies to receptions recorded after the change; boxes already received keep what was recorded. See [Receive stock](/docs/en/inventory/receive), [Order approval policy](/docs/en/orders/approval-policy) and [Stock corrections](/docs/en/inventory/corrections).

**Criticality** is stored, shown on the supply and included in exports. On the current release it does not change alerts, replenishment or approvals.

## Statuses

| Status | Label | Meaning |
| - | - | - |
| `draft` | **Draft** | Every new supply starts here, whether created in the form or by CSV import. It cannot be added to orders. |
| `active` | **Active** | The supply can be added to new orders, and it appears when someone picks a supply by name on the receiving screen. |
| `inactive` | **Inactive** | A soft retirement. The supply, its boxes and its history stay; it cannot be added to new orders. |

```mermaid theme={null}
stateDiagram-v2
  [*] --> draft: Create supply
  draft --> active: Activate
  active --> inactive: Deactivate
  inactive --> active: Activate
```

There is no way back to `draft`, and supplies cannot be deleted. Deactivate a supply you no longer use.

### Why only active supplies can be ordered

When someone adds a supply to an order, muveya copies the supply's SKU, name, unit, category, high-value flag and current cost onto the order line. That copy only means something if the unit is final, so the order screen offers active supplies only, and the server refuses any other with `orders.catalog_item_unavailable`: **This supply is not active in the catalog.** Order lines that were already added keep their copy even if the supply is later deactivated or edited. See [Create and track orders](/docs/en/orders/create-and-track).

## The supply detail page

Open a supply from the list. The page title is the supply name, with **Back to catalog** above it.

* **If you hold `catalog.manage`**, you see the same form as on creation, with the current values. **SKU** is locked and says **The SKU identifies this supply and cannot be changed.** Click **Save changes**; **Supply saved** confirms it.
* **Otherwise**, you see a read-only list: **SKU**, **Category**, **Unit**, **Packaging**, **Description**, **Criticality**, the four tracking choices as **Yes** or **No**, and **Cost** if you hold `catalog.cost.read`.

Below the details, every reader sees:

1. **Status**, for example **Status: Draft**, with **Only active supplies can be added to new orders.**
2. **Presentations**: how the supply is bought and received. See [Presentations and codes](/docs/en/catalog/presentations-and-codes).
3. **Supply cost**, only for members who hold both `catalog.manage` and `catalog.cost.read`. See [Costs](/docs/en/catalog/costs).

### Activate or deactivate

<Steps>
  <Step title="Open the supply">
    Go to **Catalog** and click the supply name.
  </Step>

  <Step title="Check the unit">
    For a supply that is not active, the status section says **Activation makes this supply orderable and fixes its unit:** followed by the unit. If you changed the unit and have not saved yet, it says **Save or discard the unit change before activating.**
  </Step>

  <Step title="Click the button">
    The button reads **Activate and fix unit** when activation will also fix the unit, **Activate supply** when the unit is already fixed, and **Deactivate supply** when the supply is active.
  </Step>
</Steps>

## The unit becomes fixed

Stock, orders and presentations are all counted in the supply's base unit, so changing it after use would change the meaning of recorded quantities. muveya protects the unit:

* The unit becomes fixed the first time the supply is *activated*, or the first time stock of the supply is *received*, even while it is still a draft.
* Once fixed, it stays fixed, also after deactivation. The form shows the unit as text with **This unit is protected and cannot be changed. You can edit the other details.**
* Everything else except the SKU stays editable: name, description, category, packaging, criticality and the tracking choices.

While the unit is not fixed, you can change it and save it together with the other fields. Before you save, the form shows **Selected change:** with the new unit and a **Discard unit change** button. Changing the unit has consequences:

* A cost recorded for the old unit moves to `review_required` and must be confirmed again. See [Costs](/docs/en/catalog/costs).
* A presentation published under the old unit cannot be used for receiving until you correct it, which republishes it under the current unit.

If the unit cannot be checked or has changed meanwhile, the form tells you:

| Message | What to do |
| - | - |
| **Checking unit…** | Wait a moment. |
| **The unit cannot be saved with the information you reviewed. Review it again or discard that change to save the other details.** | Someone changed or fixed the unit while you were editing. Review the current unit or click **Discard unit change**. |
| **We could not check whether this unit can be changed. Try again, or save the other details.** | Click **Try again**. |
| **The unit configuration needs review. You can edit the other details.** | The stored unit data is inconsistent. Write to [team@muveya.com](mailto:team@muveya.com) with the supply's SKU. |
| **You do not have permission to review this unit.** | Ask for `catalog.manage`. |

## Identifiers

| Identifier | Where you see it | Used for |
| - | - | - |
| SKU | Everywhere in the console | Your own code for the supply. It is what people search by and what the CSV import uses to detect duplicates. |
| `itemId` | In the address bar, `/catalog/items/:itemId` | The permanent internal id. The API and MCP use it, for example `GET /v1/catalog/items/{itemId}`. |
| `categoryId` | On the CSV import screen | The category's internal id, needed in CSV files. |
| Package codes (GTIN, supplier and internal codes) | Under **Presentations** | Finding a presentation when receiving. See [Presentations and codes](/docs/en/catalog/presentations-and-codes). |

The console always shows names, never raw ids, except on the CSV import screen where you need to copy category ids.

## Reading the catalog outside the console

The public API reads the catalog with `GET /v1/catalog/items` and `GET /v1/catalog/items/{itemId}` (scope `catalog:read`), and the MCP tool `catalog.search` finds supplies by name or SKU (active ones by default). Both are read-only: supplies are created and edited only in the console or through a CSV import. See the [API reference](/docs/en/api-reference/introduction) and [MCP tools](/docs/en/mcp/tools).

## What the system records

* The supply, with status `draft`, when it is created.
* When the unit is fixed: who fixed it and when.
* Field edits and status changes update the supply. On the current release they are not written as separate audit entries; CSV imports, exports and package code retirements are.

## What can go wrong

| Message | Cause | What to do |
| - | - | - |
| **Complete this field.** | A required field is empty. | Fill it in. |
| **Use no more than 64 characters.** (or 200, 2000) | A text is too long. | Shorten it. |
| **Use letters, numbers, dots, underscores, slashes or hyphens.** | The SKU has spaces or other characters. | Remove them. |
| **Choose a valid option.** | No category, unit or criticality selected. | Pick one. |
| **This SKU already exists. Use a different code.** | `catalog.sku_taken`: another supply has that SKU. | Use another SKU, or open the existing supply. |
| **This category is no longer available. Choose another one.** | `catalog.category_not_found`. | Choose a category from the list. |
| **The unit changed or requires review. Check its current configuration before activating.** | `catalog.measurement_conflict` on activation. | Reload the supply, check the unit and activate again. |
| **Your account does not have permission for this action.** | You lack `catalog.manage`. | Ask a workspace administrator. |
| **This record is not available in the active dental clinic account.** | The supply does not exist in the dental clinic you are working in. | Check the active dental clinic. |
| **Review the entered values before trying again.** | The server rejected a value. | Check each field against the table above. |
| **This supply is not active in the catalog.** | Seen on orders: the supply is draft or inactive. | Activate the supply. |

## Related pages

<CardGroup cols={2}>
  <Card title="Categories" icon="tags" href="/docs/en/catalog/categories">
    Create the groups every supply belongs to.
  </Card>

  <Card title="Presentations and codes" icon="barcode" href="/docs/en/catalog/presentations-and-codes">
    Describe how a supply is bought and the codes printed on it.
  </Card>

  <Card title="Costs" icon="coins" href="/docs/en/catalog/costs">
    Record costs and understand who can see them.
  </Card>

  <Card title="Import and export" icon="file-csv" href="/docs/en/catalog/import-export">
    Create many supplies at once from a CSV file.
  </Card>

  <Card title="Receive stock" icon="truck-ramp-box" href="/docs/en/inventory/receive">
    Put stock of a supply into a warehouse.
  </Card>

  <Card title="Create and track orders" icon="cart-shopping" href="/docs/en/orders/create-and-track">
    Order active supplies for a location.
  </Card>
</CardGroup>


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