How quantities and units are read and converted
- Utilisateur
- Admin
Hyperfox sets the quantity and the unit (packaging, UOM) of each line and checks the unit against the item. Hyperfox then converts the line before it reaches your ERP. Most of this applies to stock orders.
These rules explain why 12 boxes can become 12 pieces and why a line shows "→ 240 × Stuk". They also explain why 1.5 kg stays 1.5 kg or becomes 1.5 pieces. To correct a line, change the quantity and the unit.
Where the quantity comes from
Hyperfox reads the quantity as the document states it, in the unit the document uses. For example, "12 boxes" gives 12 with the unit box. It does not convert anything while reading.
Wrong quantities almost always come from reading the wrong number, not from a calculation. The wrong number can be the weight column instead of the quantity column, or the stock on hand in a list of items. It can also be the number of packages instead of pieces, or a figure in the item name such as "450st". On a spreadsheet, Hyperfox first finds which column holds the quantity. A sheet with several number columns makes that harder. Hyperfox skips hidden rows, columns and sheets of an Excel file. The fix is an instruction on the quantity field that says which number to take. Steer how the AI reads a field gives the steps.
How the unit is chosen
Hyperfox reads the unit word from the line, such as "doos", "box", "COL" or "ST". It matches that word to your list of units, the same way it matches items. Matching uses the columns your admin set as searchable, usually the unit code and its name. A unit word your list does not know, or an abbreviation only one customer uses, may match the wrong unit or none.
The unit check: why boxes can become pieces
In a stock order, every item has its own units. These are the units the item can be ordered in, each with how many base units it holds. On many environments, this is the list Item unit code, with the column Base unit quantity. The base unit is the item's smallest unit, often a piece.
After matching, Hyperfox checks every line:
- If the matched unit is one of the item's units, the line keeps it.
- If the unit is not one of the item's units, Hyperfox replaces it with the item's base unit.
- If no unit was read at all, Hyperfox sets the item's base unit.
- If the item has no units of its own, any unit is allowed and the line keeps the matched unit.
- If the item came from a Codex correction, Hyperfox leaves the unit as it is.
This check does not change the quantity. So when a customer orders "12 boxes" and the item has no box among its units, the line becomes 12 pieces. This is the most common cause of "boxes read as pieces". The cause is a box unit missing from that item's units in your reference data, not a reading error.
Items ordered by weight
Some items are sold by the piece but ordered in kilograms, and some are sold by weight but ordered in pieces. To Hyperfox, kilogram is a unit like box or pallet. Hyperfox takes the weight of a piece, such as 500 g, only from your reference data. Neither the reading nor the unit check converts a quantity.
- If kilogram is one of the item's units, with its Base unit quantity, the line keeps the kilograms read from the document. The hint under the quantity shows what your ERP receives. For an item of 500 g whose kilogram holds 2 pieces, 1.5 kg shows "→ 3 × Stuk".
- If the item has units of its own and kilogram is not among them, the unit check replaces kilogram with the base unit. The check keeps the quantity, so 1.5 kg becomes 1.5 pieces. Your ERP receives 1.5 pieces, because Hyperfox does not convert a line in the base unit.
- If kilogram is the item's base unit, kilogram is always allowed for that item, next to the item's other units. If piece is one of its units, a line of 5 pieces of 250 g stays 5 pieces in Hyperfox. When Hyperfox sends the order, it converts the line to kilograms and rounds up to a whole kilogram, so 1.25 kg becomes 2 kg.
One thing sets whether an order in kilograms reaches your ERP in pieces. The item must have kilogram among its units, with the right Base unit quantity. The hint under the quantity shows the result before you validate. If there is no hint, Hyperfox sends the line as it stands.
The list marked "Used for unit conversions"
In a stock-order environment, one reference data list holds every item's units and how many base units each holds. Usually this is the list Item unit code. In Admin settings > Master Data or Reference Data, that list carries the setting Used for unit conversions. Hyperfox normally switches this setting on when it sets up your environment. The setting is listed on Master Data. Switching the setting off stops every conversion.
Hyperfox reads that list in two places. While reading an order, it takes from the list the units an item allows, together with the item's base unit. When Hyperfox sends the order, the conversion to the base unit runs only if such a list exists and holds records. Without that list, Hyperfox keeps whatever unit it read for any item and sends every line in the unit you validated.
This setting stays as Hyperfox set it up. If your ERP receives units that differ from the ones you validated, your admin checks the item's units. The admin also checks the Base unit quantity of each unit and whether a list is marked.
What you see in the validation screen
- The unit picker on a line shows only the units of its item. An item without units of its own shows every unit.
- When you change the item, Hyperfox checks the unit again. If the current unit is not one of the new item's units, the line switches to a unit of the new item. That is usually its base unit. Every item change can therefore change the unit.
- Under the quantity, a hint such as "→ 240 × Stuk" shows the line converted to the base unit, here 20 boxes of 12 pieces. If the line is already in the base unit, there is no hint.
- Hyperfox flags a line whose unit is not valid for its item with "Unit is not valid for this item". Validate stays blocked until you choose a valid unit. Hyperfox shows this message in English.
- The Total row sums the quantities per unit, so you can compare it with the document.
What is sent to your ERP
In a stock-order environment, Hyperfox converts every line to the item's base unit when it sends the order. This applies to webhooks and export profiles alike. Hyperfox multiplies the quantity by the Base unit quantity of the line's unit and rounds up to a whole number. The order in Hyperfox keeps the unit you validated. Only what Hyperfox sends is converted.
If a line is already in the base unit or has no item, Hyperfox sends it as it is. The same goes for a line whose item has no entry for the line's unit. If the conversion fails, Hyperfox does not send the order, and the order gets the status Submit Failed. What each order and inquiry status means lists every status.
Only a converted line is rounded. Half a box of 12 pieces becomes 6 pieces, and 0.3 box becomes 4 pieces (3.6 rounded up). Hyperfox sends a line that is already in the base unit with the quantity you validated, a fraction included.
Hyperfox never chooses the smallest unit on its own. It converts to the base unit your reference data gives the item, and only with the Base unit quantity your reference data holds. Outside a stock-order environment, Hyperfox sends every line in the quantity and unit you validated. Your ERP or the export then does any conversion.
Does it learn
When you change the unit on a line and validate, Hyperfox records a Codex entry for that customer and that item. On later orders of that customer and item, Codex applies your correction when Hyperfox again matches the unit you replaced, for a similar text. If a unit word matches the wrong unit for every customer, an instruction on the unit field fixes it better. How Codex learns from your corrections explains the entries.
What you can change
When boxes become pieces, whoever maintains your reference data adds the box unit, with its Base unit quantity, to that item's units. The steps are in Add, edit and delete reference data records.
When the quantity comes from the wrong column, an admin adds an instruction to the quantity field.
When a customer's unit word is not recognised, an operator corrects and validates. Codex then learns the word for that customer and item. An admin can also add an instruction to the unit field that says what the word means.
When the ERP receives the wrong number of pieces, whoever maintains your reference data checks the Base unit quantity of that item and unit.
If an order in kilograms must reach your ERP in pieces, or the reverse, the item needs kilogram or piece among its units. Whoever maintains your reference data adds that unit, with its Base unit quantity.
What each lever changes, and what it does not, is in What you can change so Hyperfox reads your orders better.