> ## 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.
# Costs
> Record what a supply costs, understand cost states and history, and control who can see costs and how orders use them.
Each supply can carry a current cost: an amount per base unit, in one currency. Costs are confidential. The server removes them from every read unless the reader holds the cost permission, and each change keeps the previous cost in a history. When someone adds the supply to an order, the line keeps a copy of the cost in effect at that moment.
## Who can do it
| Action | Permission |
| - | - |
| See costs in the console, in CSV exports and on order lines | `catalog.cost.read` (**View supply costs**) |
| Record a cost in the console | `catalog.manage` *and* `catalog.cost.read` |
| Read costs through the public API | An API key with `catalog:read` *and* `catalog.cost:read` |
No role includes `catalog.cost.read`, not even Owner: it is always granted explicitly, member by member. Holding it does not let anyone change costs or units. See [Roles and permissions](/docs/en/account/roles-and-permissions).
## Where costs appear
| Place | What you see |
| - | - |
| **Catalog** list | A **Cost** column, only with `catalog.cost.read`. |
| Supply detail, read-only view | A **Cost** row, only with `catalog.cost.read`. |
| Supply detail, **Supply cost** section | The form to record a cost, only with `catalog.manage` and `catalog.cost.read`. |
| CSV import | Optional `cost` and `currency` columns. See [Import and export](/docs/en/catalog/import-export). |
| CSV export | Six cost columns, only with `catalog.cost.read`. |
| Order lines | The cost copied when the line was added, only with `catalog.cost.read`. |
## Amounts, currencies and minor units
muveya stores every amount as a whole number of the currency's *minor units*, such as cents, together with a three-letter uppercase ISO 4217 currency code. This keeps amounts exact.
| You mean | Stored `cost` | `currency` |
| - | - | - |
| USD 12.00 | `1200` | `USD` |
| USD 0.35 | `35` | `USD` |
| BRL 7.90 | `790` | `BRL` |
| CLP 1,200 | `1200` | `CLP` |
* **In the console** you type the amount in normal units: digits, optionally followed by a decimal point or comma and at most as many decimals as the currency uses (two for USD and BRL, none for CLP). Do not use thousands separators: `1250.50` is valid, `1,250.50` is not. The console converts the amount to minor units exactly and never guesses the currency.
* **In CSV files and the API** the amount is already in minor units: a whole number such as `1200`.
* `0` is a valid cost and is different from having no cost. Negative amounts are not accepted.
## Record a cost
Go to **Catalog** and click the supply name.
It is at the bottom of the page: **Cost changes are saved separately and keep their history.** The line **Cost per** followed by the unit, for example **Cost per Box**, tells you which base unit the amount will apply to.
Type the **Amount** (**Choose a currency and enter the amount without thousands separators.**) and the **Currency**, for example `USD`. If the supply already has a cost, both fields start with it.
Click **Save cost**. **Cost saved** confirms it.
What happens when you save:
* The previous cost, if any, is closed and kept in the history.
* The new amount becomes the current cost from that moment.
* The cost is tied to the supply's unit as it was when you reviewed it. If the unit changed in the meantime, nothing is saved and the form says **The unit you reviewed has changed. Review the current unit before confirming this amount.**, then **Current unit:** with the unit and a **Review cost for the current unit** button. Click it, check the amount and save again.
The creation form has no cost field. A new supply gets its first cost here or from a CSV import.
Use one currency for all the supplies of your dental clinic. An order's value adds up only the lines in the currency of its first costed line; lines in another currency are left out of the value.
## Cost states
Every read that includes a cost also includes `costStatus`. Read the state before using the amount.
| `costStatus` | What the console shows | Meaning | What to do |
| - | - | - | - |
| `unset` | **Not set** | No cost has ever been recorded. This is not the same as a cost of zero. | Record a cost if you want orders to have a value. |
| `verified` | The amount and **Cost per** the unit | The amount applies to the supply's current unit. | Nothing. |
| `review_required` | The amount, **Recorded per** the old unit and **Needs confirmation for the current unit.** | A previous amount exists, but it was recorded for a unit the supply no longer has, or it comes from older data without a unit. Do not multiply it by quantities of the current unit. | Save the cost again in **Supply cost** to confirm it for the current unit. |
| `invalid` | **The previous cost data needs review.**, with the amount if it could be read | The stored cost data is inconsistent. It is never converted into money or treated as missing. The cost form is disabled. | Write to [team@muveya.com](mailto:team@muveya.com) with the supply's SKU. |
A `review_required` cost usually appears after someone changes the supply's unit while it is still editable. See [Catalog items](/docs/en/catalog/items#the-unit-becomes-fixed).
Two more messages can appear where a cost would be:
* **Cost information is unavailable.**: you have the permission but the cost could not be read. Reload the page.
* **The recorded unit is unavailable.**: the amount is shown but its unit basis is missing.
## Cost history
Every time a cost is replaced, the previous one is closed and stored with its amount, currency, the moment it took effect, who recorded it and the unit it applied to. The history is append-only: nothing in it is edited or deleted.
The current release has no screen, API operation or MCP tool to browse the cost history. Order lines keep the cost they copied, so past orders still show what was paid at the time.
## Redaction: who sees what
Costs are removed on the server, not hidden in the screen. For a reader without `catalog.cost.read`:
* The fields `cost`, `currency`, `costStatus` and `costMeasurement` are absent from every catalog read: the console, `GET /v1/catalog/items`, `GET /v1/catalog/items/{itemId}` and the MCP tool `catalog.search`. Absent means absent, never zero.
* A CSV export does not contain the six cost columns at all.
* Order lines do not show their cost copy.
* Saving a cost never sends the amount back in the response.
The order's total value follows a separate permission, `orders.value.read`. See [Create and track orders](/docs/en/orders/create-and-track).
This is how a cost looks in an API read by a key that holds `catalog.cost:read`:
```json theme={null}
{
"itemId": "665f1a2b3c4d5e6f7a8b9c0d",
"sku": "GLV-NIT-M",
"name": "Nitrile gloves size M",
"categoryId": "665f1a2b3c4d5e6f7a8b9c01",
"unitOfMeasure": "pair",
"criticality": "high",
"tracksLot": true,
"tracksSerial": false,
"tracksExpiry": true,
"highValue": false,
"status": "active",
"costStatus": "review_required",
"cost": 1200,
"currency": "CLP",
"costMeasurement": {
"unitOfMeasure": "unit",
"measurementVersion": 1,
"quantityProtocol": "base_number_v1"
}
}
```
Here the amount was recorded per `unit`, but the supply is now counted in `pair`, so the amount must be confirmed before it applies. `costMeasurement` names the unit, its version and the quantity rule (`base_number_v1`, whole numbers of the base unit) the amount was recorded for.
## How orders use the cost
When someone adds a supply to a draft order, muveya copies the cost in effect at that moment onto the line, together with the SKU, name, unit, category and high-value flag.
| Supply's `costStatus` when the line is added | Result |
| - | - |
| `verified` | The line keeps the amount and currency. |
| `unset` | The line is added without a cost and adds nothing to the order's value. |
| `review_required` or `invalid` | The line is refused with `catalog.cost_unverified`. The order screen shows **The record changed or already exists. Review it before trying again.** Confirm the cost on the supply and add the line again. |
* Changing the cost later does not change lines already added.
* The order's value is the sum of cost times requested quantity over the lines that have a cost, in the currency of the first of them.
* Approval rules with a minimum or maximum order value use that value, so supplies without a cost do not count toward it. See [Order approval policy](/docs/en/orders/approval-policy).
## What the system records
* The current cost, with its currency, the moment it took effect, who recorded it and its unit basis.
* The closed previous costs, in the history.
* On each order line, the copied cost and currency.
## What can go wrong
| Message | Code | What to do |
| - | - | - |
| **Enter an exact, non-negative amount without thousands separators.** | | Remove separators and extra decimals. |
| **Use a three-letter uppercase currency code, such as USD.** | | Type a code like `USD`. |
| **Complete this field.** | | Enter an amount. |
| **The unit you reviewed has changed. Review the current unit before confirming this amount.** | `catalog.measurement_conflict` | Click **Review cost for the current unit** and save again. |
| **The change was not confirmed. Try again.** | `catalog.cost_clock_conflict` | The new cost did not get a later timestamp than the current one. Save again. |
| **The previous cost data needs review.** | `catalog.cost_unverified` | The cost or its history cannot be used safely. Write to [team@muveya.com](mailto:team@muveya.com). |
| **The unit configuration needs review. You can edit the other details.** | `catalog.measurement_unverified` | Write to [team@muveya.com](mailto:team@muveya.com) with the SKU. |
| **Your account does not have permission for this action.** | `tenants.insufficient_role` | Ask for `catalog.manage`. |
| **This record is not available in the active dental clinic account.** | `catalog.item_not_found` | Check the active dental clinic. |
| **A required field is missing.** (CSV import row) | `catalog.cost_incomplete` | The row has a cost without a currency, or a currency without a cost. Give both or neither. |
None of these errors applies the proposed change. Review the information before trying again.
## Related pages
Supplies, units and statuses.
Costs in CSV files.
Where cost copies and order values appear.
Approval rules based on order value.
Grant **View supply costs**.
`catalog:read` and `catalog.cost:read`.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.