> ## Documentation Index
> Fetch the complete documentation index at: https://help.mathership.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Unit Conversions
> Understand how Mathership converts ordered products, packaging units, and recipe quantities into ingredient stock units
# Unit Conversions
Unit conversions define how ordered products are converted into ingredient stock, and how quantities entered in packaging units are translated to the ingredient's base unit throughout the app.
They are used when Mathership receives orders, updates inventory through stock counts, transfers, or waste, calculates stock balances, creates inventory ledger entries, and calculates inventory value.
Turn ordered vendor products into ingredient stock quantities.
Enter quantities in boxes, bags, cases, bottles, or base units.
Store all inventory movements in the ingredient's base unit.
## What unit conversions are used for
Use unit conversions when a product is ordered in one unit but inventory is tracked in another unit.
Common examples:
* A vendor product is ordered as a box but stock is tracked in kilograms
* Milk is ordered in packs but inventory is tracked in liters
* Bottles are ordered as cases but stock is tracked as single bottles
* A recipe uses grams but the ingredient is stored in kilograms
* POS sales reduce stock in smaller units than the purchasing unit
## Where unit conversions appear in the UI
Unit conversion is not a standalone page.
It is built into every screen where quantities are entered or displayed.
| Feature | How unit conversion is used |
| ---------------------- | ------------------------------------------------------------------ |
| Product mapping | Define packaging levels and conversion factor for a vendor product |
| Receiving orders | Converts received product quantity to ingredient base units |
| Stock counts | Enter counted quantities in base unit or packaging units |
| Transfers | Enter transferred quantities in base unit or packaging units |
| Waste | Enter wasted quantities in base unit or packaging units |
| Ingredient detail page | Shows on-hand in packaging breakdown format |
| Recipe detail page | Shows ingredient quantities per line |
| Ledger | Stores all movements in base units |
## How unit conversions work
Mathership separates three concepts:
| Concept | Meaning |
| -------------------- | -------------------------------------------------------------------- |
| Product unit | The unit or packaging used when ordering a product |
| Ingredient base unit | The unit used to track inventory for an ingredient |
| Conversion factor | The amount of ingredient stock created from one ordered product unit |
### Example
| Ordered product | Ingredient | Conversion |
| --------------- | ----------- | ---------- |
| 1 box tomatoes | Tomatoes | 10 kg |
| 1 pack milk | Milk | 10 L |
| 1 case beer | Beer bottle | 24 bottles |
If you receive 2 boxes of tomatoes and one box equals 10 kg, Mathership creates a receipt of 20 kg.
## Base units
Each ingredient has a base unit.
The base unit is the main unit used for inventory balances, ledger entries, reports, and recipe usage.
| Ingredient | Base unit |
| ---------- | --------- |
| Flour | kg |
| Milk | L |
| Eggs | pcs |
| Ribeye | kg |
| Wine | bottle |
Choose ingredient base units carefully. Inventory movements, reports, recipes, and cost calculations depend on the base unit.
## Standard unit conversions
Mathership recognises standard weight and volume units and can automatically convert between them.
### Weight units
| Unit | Code |
| --------- | ---- |
| Milligram | mg |
| Gram | g |
| Kilogram | kg |
| Ounce | oz |
| Pound | lb |
### Volume units
| Unit | Code |
| ---------- | ---- |
| Milliliter | ml |
| Centiliter | cl |
| Deciliter | dl |
| Liter | L |
These conversions are used automatically when the bottom packaging level's unit differs from the ingredient's base unit.
For example, if the bottom level is in grams and the base unit is kilograms, Mathership multiplies by `0.001` automatically.
## Product-to-ingredient conversion
Unit conversion is configured through product-to-ingredient mapping.
A product mapping defines how a vendor product becomes an ingredient quantity.
| Field | Meaning |
| ---------------- | ---------------------------------------------------------------------------- |
| Vendor product | Product ordered from the vendor |
| Ingredient | Ingredient that receives stock |
| Target unit | The ingredient's base unit — set automatically when you select an ingredient |
| Packaging levels | The nested packaging structure of the product |
| Factor | Quantity added to inventory per ordered product unit |
### Example
| Vendor product | Ingredient | Factor |
| -------------- | ---------- | ------ |
| Tomato box | Tomatoes | 10 kg |
| Milk pack | Milk | 10 L |
| Flour sack | Flour | 25 kg |
See [Product Mapping](/en/restaurants/inventory/product-mapping) for the full setup guide.
## Conversion factor
The conversion factor tells Mathership how much ingredient stock one ordered product unit creates.
**Received inventory quantity = Ordered quantity × Conversion factor**
| Ordered quantity | Factor | Inventory receipt |
| ---------------- | -----: | ----------------: |
| 1 box | 10 kg | 10 kg |
| 2 boxes | 10 kg | 20 kg |
| 5 boxes | 10 kg | 50 kg |
## Packaging levels
Packaging levels describe nested product packaging.
They are useful when a product has multiple layers.
### Example structure
| Level | Quantity per parent | Unit |
| ----- | ------------------: | ---- |
| Box | 6 | Pack |
| Pack | 1 | kg |
In this example, one box contains 6 packs and each pack contains 1 kg.
The total quantity per box is 6 kg.
## How packaging level conversion works
When you enter a quantity in a packaging unit, Mathership:
1. Finds the selected packaging level in the hierarchy
2. Walks down through each level multiplying by `quantity_per_parent`
3. Reaches the bottom level which has a unit, such as kg or L
4. Applies any standard unit conversion if the bottom level unit differs from the ingredient's base unit
5. Returns the final quantity in base units
This calculation happens automatically every time you enter a quantity in a stock count, transfer, or waste entry.
## Packaging example
A vendor sells flour as a box with 4 bags.
Each bag contains 2.5 kg.
| Packaging level | Quantity per parent | Unit |
| --------------- | ------------------: | ---- |
| Box | 4 | Bag |
| Bag | 2.5 | kg |
| Ordered product | Inventory quantity |
| --------------- | -----------------: |
| 1 box | 10 kg |
| 2 boxes | 20 kg |
| 3 boxes | 30 kg |
## Entering quantities in packaging units
When packaging levels are configured on an ingredient, the stock count, transfer, and waste sheets let you enter quantities in those packaging units instead of the base unit.
The unit dropdown shows:
* Base unit, such as kg
* Each packaging level by name, such as Box or Bag
When you select a packaging unit, the converted base quantity is shown in real time below the input field — for example `= 20 kg` — so you can confirm the conversion before saving.
The system always stores the quantity in base units. The packaging unit selection is only for convenient entry.
## Default unit selection
When you open a stock count, transfer, or waste entry, Mathership automatically selects the most appropriate unit to display.
| Situation | Default behavior |
| ------------------------------------------------- | ------------------------------------------------------------------------ |
| Ingredient has packaging levels and stock on hand | Mathership picks the packaging level that gives the most readable number |
| Ingredient has no packaging levels | Mathership defaults to the base unit |
## Packaging breakdown display
Throughout the app, on-hand quantities are shown as a packaging breakdown rather than just a raw base unit number.
Format:
**primary level / base quantity / secondary level**
Example for flour with packaging levels Box and Bag:
| Base quantity | Breakdown display |
| ------------: | -------------------- |
| 30 kg | 5 Box / 30 kg |
| 7 kg | 1 Box / 7 kg / 1 Bag |
This format appears in:
* Ingredient picker dropdowns
* Stock count sheet
* Transfer sheet
* Waste sheet
* Ingredient detail panel within storage units
* Ledger page
* Suggestion detail sheet
## AI-assisted packaging detection
The product mapping sheet has a **Get AI factor** button shown with a sparkles icon.
It reads the vendor product details and the selected ingredient and suggests:
* A conversion factor
* Packaging levels with names and quantities per parent
### Examples
| Packaging text | Suggested factor |
| -------------- | ---------------- |
| 6 x 0.75 L | 4.5 L |
| 4 x 2.5 kg | 10 kg |
| 24 bottles | 24 bottles |
Always verify AI suggestions against the actual product packaging before saving the mapping.
## Automatic factor calculation
If you configure packaging levels manually in the product mapping sheet, Mathership automatically calculates the total factor by multiplying through the hierarchy.
Example:
| Level | Qty per parent | Unit |
| ------ | -------------: | ---- |
| Carton | 12 | Pack |
| Pack | 1 | L |
Mathership calculates:
**12 × 1 = 12 L per carton**
If the mapped ingredient uses liters as the base unit, the factor becomes `12`.
## From unit and to unit
A mapping uses a source unit and a target unit.
| Field | Meaning |
| --------- | --------------------------------------------- |
| From unit | Unit detected from the product packaging |
| To unit | The ingredient's base unit |
| Factor | Converted quantity from product to ingredient |
### Common conversions
| From unit | To unit | Conversion |
| --------- | ------- | ------------- |
| g | kg | 1000 g = 1 kg |
| ml | L | 1000 ml = 1 L |
| kg | kg | 1 kg = 1 kg |
| L | L | 1 L = 1 L |
## Receiving orders
Unit conversions are used when receiving vendor orders into inventory.
| Ordered product | Ordered quantity | Factor | Ledger receipt |
| --------------- | ---------------: | -----: | ---------------- |
| Tomato box | 2 | 10 kg | `RECEIPT` +20 kg |
| Milk pack | 5 | 10 L | `RECEIPT` +50 L |
| Flour sack | 1 | 25 kg | `RECEIPT` +25 kg |
If a product has no mapping, Mathership cannot correctly convert it into ingredient stock.
## Partial receiving
When receiving an order, the received quantity can differ from the ordered quantity.
| Ordered quantity | Received quantity | Factor | Inventory receipt |
| ---------------- | ----------------- | ---------: | ----------------: |
| 10 boxes | 8 boxes | 10 kg | 80 kg |
| 5 packs | 5 packs | 10 L | 50 L |
| 6 cases | 4 cases | 24 bottles | 96 bottles |
Mathership uses the received quantity for the inventory receipt.
## Recipes and unit conversions
Recipes use ingredient quantities in the ingredient's base unit.
The ingredient base unit should match how the ingredient is normally consumed.
| Recipe item | Quantity used | Ingredient base unit |
| ------------ | ------------: | -------------------- |
| Ribeye steak | 0.3 kg | kg |
| Tomato soup | 0.15 kg | kg |
| Milk sauce | 0.2 L | L |
When a POS sale or recipe issue is posted, Mathership reduces stock using the ingredient unit.
## POS usage
POS mappings can reduce inventory through recipes or direct ingredient mappings.
| POS item | Recipe usage | Inventory issue |
| ------------ | -------------- | ---------------- |
| Ribeye steak | 300 g ribeye | `ISSUE` −0.3 kg |
| Tomato soup | 150 g tomatoes | `ISSUE` −0.15 kg |
| Cappuccino | 0.15 L milk | `ISSUE` −0.15 L |
## Inventory ledger impact
Unit conversions directly affect inventory ledger entries.
The ledger stores the converted ingredient quantity, not the vendor order quantity.
| Ordered quantity | Conversion factor | Ledger quantity |
| ---------------- | ----------------: | --------------: |
| 2 boxes | 10 kg | +20 kg |
| 5 packs | 10 L | +50 L |
| 3 cases | 24 bottles | +72 bottles |
## Cost conversion
Costs are also affected by the conversion factor.
If one ordered product costs €20 and creates 10 kg of stock, the unit cost is €2 per kg.
| Ordered product cost | Factor | Unit cost |
| -------------------- | ---------: | -----------: |
| €20.00 per box | 10 kg | €2.00/kg |
| €15.00 per pack | 5 L | €3.00/L |
| €24.00 per case | 24 bottles | €1.00/bottle |
This unit cost is used for inventory value and weighted average cost.
## Common workflows
### Create a product mapping with packaging levels
1. Open an order or go to **Manage** → **Ingredients** and open an ingredient
2. Open the product mapping sheet
3. Select the vendor product and the ingredient
4. Add packaging levels — name, quantity per parent, and unit for the bottom level
5. Click **Get AI factor** to let Mathership suggest the factor from the product details, or enter it manually
6. Review the suggested packaging levels and factor
7. Save the mapping
### Use AI-assisted factor calculation
1. Select the vendor product in the mapping sheet
2. Select the target ingredient
3. Click **Get AI factor**
4. Review the suggested packaging levels and factor
5. Adjust any values that do not match the actual product
6. Save the mapping
### Receive an order with conversions
1. Open the received order
2. Check which order items are mapped
3. Select the storage unit
4. Review the received quantity
5. Review the converted base quantity shown in the **To transfer** column
6. Post the receipt to inventory
### Fix a wrong conversion
1. Open the product mapping
2. Check the packaging levels and their quantities per parent
3. Check the bottom-level unit
4. Correct the factor or packaging levels
5. Save the mapping
6. Review affected receipts and ledger entries
## Best practices
Choose base units that match how you manage stock, such as kg for meat and vegetables, L for liquids, and pcs for eggs.
Packaging levels should match the real product structure, including order, quantity per parent, and bottom-level unit.
A wrong factor can create large stock errors, especially for cases, crates, boxes, and packs.
Do not track the same ingredient sometimes in grams and sometimes in kilograms. Use one base unit and convert everything into it.
The AI factor is a starting point. Verify the suggested factor against the actual product packaging before saving.
After changing conversion settings, review receipts and ledger entries to confirm quantities and costs look correct.
### Recommended base units
| Ingredient type | Recommended base unit |
| ---------------- | --------------------- |
| Meat | kg |
| Vegetables | kg |
| Milk and liquids | L |
| Bottled drinks | bottle or L |
| Eggs | pcs |
### Common wrong factors
| Wrong factor | Result |
| --------------------------------------- | -------------- |
| 1 box = 1 kg instead of 10 kg | Stock too low |
| 1 pack = 10 L instead of 1 L | Stock too high |
| 1 case = 1 bottle instead of 24 bottles | Stock too low |
## Common problems
Check the product mapping factor, packaging levels, from unit and to unit, whether the ordered quantity was entered correctly, and whether the product was received twice.
Check the product mapping factor, missing packaging levels, wrong bottom-level unit, and whether the product was mapped to the wrong ingredient.
Check that the product is mapped to an ingredient, the ingredient exists and is active, the ingredient has a base unit, the mapping has a valid factor, and a storage unit was selected.
Check the product price, conversion factor, received quantity, and the weighted average cost history from previous receipts.
If the AI factor creates the wrong result, check the packaging levels manually — name, quantity per parent, and bottom-level unit.
Edit the packaging levels and factor directly in the mapping sheet.
If the on-hand breakdown shows an unexpected format, check that packaging levels are configured on the ingredient and that the order field on each level correctly places them in the hierarchy from top to bottom.
## Related pages
Manage ingredients and their base units.
Map vendor products to inventory ingredients.
Receive vendor orders and convert products into ingredient stock.
View converted inventory movements and running stock balances.
Use ingredient quantities for recipes and POS stock reduction.
Analyze stock, movement quantities, costs, and inventory values.