Costs

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.

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

Open the supply

Go to Catalog and click the supply name.

Find the Supply cost section

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.

Enter the amount and currency

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.

Save

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 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. 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. This is how a cost looks in an API read by a key that holds catalog.cost:read:

{
  "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.

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.
The unit configuration needs review. You can edit the other details.	`catalog.measurement_unverified`	Write to 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.

Catalog items

Supplies, units and statuses.

Import and export

Costs in CSV files.

Create and track orders

Where cost copies and order values appear.

Order approval policy

Approval rules based on order value.

Roles and permissions

Grant View supply costs.

API scopes

catalog:read and catalog.cost:read.

Get started

Account and team

Locations and warehouses

Catalog

Inventory

Orders and approvals

Deliveries

Reports

WhatsApp

Android app

Trust and help

Who can do it

Where costs appear

Amounts, currencies and minor units

Record a cost

Cost states

Cost history

Redaction: who sees what

How orders use the cost

What the system records

What can go wrong

Catalog items

Import and export

Create and track orders

Order approval policy

Roles and permissions

API scopes

​Who can do it

​Where costs appear

​Amounts, currencies and minor units

​Record a cost

​Cost states

​Cost history

​Redaction: who sees what

​How orders use the cost

​What the system records

​What can go wrong

​Related pages

Catalog items

Import and export

Create and track orders

Order approval policy

Roles and permissions

API scopes

Who can do it

Where costs appear

Amounts, currencies and minor units

Record a cost

Cost states

Cost history

Redaction: who sees what

How orders use the cost

What the system records

What can go wrong

Related pages