Item units of measure

An item unit of measure is an alternate unit an item can be bought, sold, counted or adjusted in — a box of 4, a case of 12 — together with the conversion ratio that turns a quantity in that unit into the quantity xMatix stores. You add units to an item after it exists, on the item's Related tab, and every document line that names the item can then be entered in them.

Units are part of the item master. They come after the item (and its SKUs, if it has any) and before the first document line that uses them.

Overview

Every document line keeps one stored quantity — the Quantity that pricing, stock, invoicing and delivery count. An item unit of measure lets a person enter that quantity in a more natural unit instead. Each unit row carries:

• a Unit Of Measure — the unit's code, picked from a list (Each, Box, Pack, Barrel, Litres, MB, Minutes, Messages, KWH in the shipped setup);
• a Conversion Ratio — how many base units one of this unit contains.

When a line is entered as 2 Box on an item whose Box row has a ratio of 4, xMatix stores a quantity of 8. The unit whose ratio is 1 is the unit the stored quantity — and the price list — counts in.

When to use it

Add units when people handle the same product in more than one pack size: a distributor buys in cases and sells in pieces, a warehouse counts in cartons, a utility bills in KWH. Do not create a separate item for a case versus a single unit; add a unit to the one item instead.

You do not need any unit rows for an item that is only ever handled in one unit. A line that names no unit keeps the quantity exactly as it is typed.

How xMatix handles it

• Every line that names a unit must use one the item has. When a line is saved with a unit, xMatix looks for a unit row on that item with the same Unit Of Measure (ignoring capitals and surrounding spaces). If there is none, the line is refused with UOM is not defined for this Item. The item's own Primary Unit Of Measure does not count as a unit row — if lines will name the base unit, add a row for it with a ratio of 1.
• Two unit slots per line. Document lines have two pairs of unit fields: UOM with UOM Quantity, and UOM 1 with UOM Quantity 1. This lets one line say "2 cases and 3 pieces". The stored quantity is the sum of each unit quantity times its ratio.
• Conversion works both ways. Change the unit quantities and xMatix recalculates the line quantity. Change the line quantity instead and xMatix splits it back into the unit slots, filling the unit with the larger ratio first with whole units and putting the remainder in the other.
• The ratio is stamped on the line. Each line keeps the ratio it was converted with. Changing a unit's ratio later affects lines saved from then on; a line that was already saved keeps its quantity until someone edits it again.
• Ratios can be fractional. A ratio below 1 is allowed — with Pieces at 0.025 and Case at 1, one piece is a quantity of 0.025. Ratios hold up to six decimal places.
• Rounding. The quantity in a unit is rounded to that unit's UOM Decimal Precision (two places when it is empty). The line's stored quantity is rounded to the item's Primary UOM Decimal Precision, but never to fewer decimals than the item's finest ratio needs; when the item's precision is empty it is not rounded. Halves round away from zero.
• SKU on a unit row. Document-line conversion uses all of an item's unit rows, whichever SKU they name. The SKU on a row matters only to order capture, which offers a SKU-specific unit only for that SKU.

The conversion runs on sales order, invoice, delivery order, credit note and field sales lines; purchase order, goods receipt (on the received quantity) and bill lines; inventory adjustment and cycle count lines; claim lines; and on the quantities of scheme conditions and scheme benefits.

Where the UOM Code is used

UOM Code is a short display code, separate from the unit the lines are checked against:

• Take Order on the web and in the field app captions each unit's quantity stepper with the UOM Code (for example CS or PKT). Without one, it falls back to the unit's label from the Unit Of Measure list, then to the unit's Name. Placeholder codes such as UOM1 are ignored.
• The storefront catalogue offers an item's units only for rows that have a UOM Code and a ratio above zero. If no row has a ratio of 1, it adds the item's Primary Unit Of Measure as the base unit.
• Order capture (typed text or a photographed order slip in the field app) recognises a unit word in the order when it matches a row's UOM Code. Common spellings are treated alike — for example case and cs, pack and pkt, pieces and pcs — and the quantity is converted to base units.

Take Order and the storefront leave out a unit row whose ratio is zero or less. An item left with no usable unit rows is ordered in its base unit with no unit written on the line.

Prerequisites

• The item exists. See Items.
• The unit you need is on the Unit Of Measure list. An administrator adds values to it (see Configuration).
• Your security profile lets you create item units of measure (see Permissions).

Procedure

Step 1 — Open the item

Open the item from the items list and select its Related tab. The item units of measure list is one of the lists there.

Step 2 — Add a unit

1. In the item units of measure list, select New. The form opens with the item already filled in.
2. Optionally type a Name and a UOM Code (the short code Take Order and the storefront show, such as CS).
3. Leave SKU empty so the unit applies to every SKU, or pick a SKU to tie the unit to it for order capture.
4. Under UOM Measurement, pick the Unit Of Measure.
5. Enter the Conversion Ratio — how many base units one of this unit contains. A box of 4 has a ratio of 4.
6. Save.

The unit is now on the item's list, and lines for this item accept it straight away.

Step 3 — Add the base unit if lines will name it

If documents will be entered in the base unit as well (for example "3 Each" next to "2 Box"), add a second unit with that Unit Of Measure and a Conversion Ratio of 1.

Step 4 — Enter a line in the unit

On a document line for the item, pick the unit in UOM and type the UOM Quantity. Use UOM 1 and UOM Quantity 1 for a second unit on the same line. Save the line. The line's quantity becomes the converted total, and the line keeps the ratio it used.

Step 5 — Change or remove a unit

Open the unit from the item's list. Select Edit to change it, or Delete to remove it.

• A new ratio applies to lines saved afterwards. Existing lines keep their quantities until they are edited.
• After a unit is deleted, new lines can no longer use it, and editing an older line that still names it is refused with UOM is not defined for this Item. Correct the unit on such a line before you save it.

Fields

Business rules

• Unit and ratio are required. Saving a unit without a Unit Of Measure, or with a Conversion Ratio of zero or less, is refused.
• Lines must use a defined unit. A line naming a unit the item has no row for is refused with UOM is not defined for this Item.
• No silent zero lines. If a unit row with a ratio of zero still exists from before the ratio check, a line that enters a quantity in it is refused with Conversion Ratio is not configured for UOM '…' on this Item.
• Quantity calculation. Line quantity = UOM Quantity × its ratio + UOM Quantity 1 × its ratio. Entering the line quantity directly splits it back into the units, larger ratio first.
• Rounding. Unit quantities round to the unit's precision; the line quantity rounds to the item's precision raised to what its finest ratio needs.
• One row per unit. Do not give an item two rows with the same Unit Of Measure. Lines use only one of them, and you cannot choose which.
• No numbering. Unit rows have no document numbering setting.

Example

A distributor stocks a hand wash, item HW-250, whose Primary Unit Of Measure is Each. It sells to shops in boxes of 4 and to wholesalers in cases of 24.

1. On the item's Related tab, the inventory controller adds three units: Each with ratio 1, Box with ratio 4 and UOM Code BX, and Pack with ratio 24 and UOM Code CS.
2. A sales order line is entered with UOM Pack, UOM Quantity 2, UOM 1 Box and UOM Quantity 1 3. On save the line quantity becomes 2 × 24 + 3 × 4 = 60.
3. The salesperson then changes the line quantity to 50. xMatix splits it back: 2 Pack (48) and 0.5 Box. Because the Box row was created from the form, its precision is 0, so the Box quantity is stored as 1. The line quantity stays 50 even though the unit slots now read 52 — set a precision on the Box unit if half boxes are real.
4. In Take Order the steppers for this item read BX and CS, and the Each stepper shows the list label because that row has no UOM Code.

Training

Practice exercise

In a sandbox, open an active item whose Primary Unit Of Measure is Each.

1. Add a unit Box with ratio 6, and a unit Each with ratio 1.
2. Create a sales order line for the item with UOM Box and UOM Quantity 2.
3. Add a second line with UOM Barrel and any quantity.

Expected result: the first line saves with a quantity of 12. The second line is refused with UOM is not defined for this Item, because the item has no Barrel unit.

Quick reference

• Units live on the item's Related tab.
• Conversion Ratio = base units in one of this unit; it must be above zero.
• The ratio-1 unit is the unit quantities and prices count in.
• A line that names a unit needs a matching row — add a row for the base unit too if lines will name it.
• Two unit slots per line: UOM and UOM 1.
• A changed ratio affects lines saved afterwards only.
• UOM Code is a display code for Take Order, the storefront and order capture — lines are not checked against it.
• The SKU on a unit row matters only to order capture.

Permissions

Item units of measure are an ordinary entity with View, Create, Edit and Delete permissions. In the shipped security profiles — System Admin, Standard User, Sales, Sales Executive, Sales Manager and Service — they have full access across the organisation. A profile without Create access cannot add units, and one without Delete access cannot remove them.

Units are always reached through their item, so a user also needs to be able to open the item.

Configuration

Common problems

"UOM is not defined for this Item"

The line names a unit that the item has no row for — often the item's base unit, or a unit that was deleted. Add a row for that unit on the item's Related tab (ratio 1 for the base unit), or pick a unit the item has.

"Conversion Ratio must be greater than zero"

You saved a unit with an empty or zero Conversion Ratio. Enter how many base units one of this unit contains.

"Quantity Unit Of Measure is required"

The unit row has no Unit Of Measure. Pick one from the list before you save.

"Conversion Ratio is not configured for UOM '…' on this Item."

The unit row is an older one saved with a ratio of zero. Open it, enter the correct Conversion Ratio and save, then save the line again.

My quantity in boxes was rounded to a whole number

Unit rows created from the form store a UOM Decimal Precision of 0, so quantities in that unit round to whole numbers. Ask your administrator to set a precision for the unit.

A unit does not show in the storefront

The storefront only lists units that have a UOM Code and a ratio above zero. Fill in the UOM Code.

Common questions

Do I need a unit row for the base unit?

Only if document lines will name it. A line with no unit keeps its quantity as typed, so an item sold only in its base unit needs no rows at all. But once a line names a unit, that unit must exist as a row on the item — and the Primary Unit Of Measure does not count. If people will enter "3 Each" alongside "2 Box", add an Each row with a ratio of 1. Take Order already handles an item with no rows by ordering it in its base unit without writing a unit to the line.

What happens to existing orders when I change a ratio?

Nothing until they are edited. Each line stamps the ratio it used when it was saved, and its quantity stays as it is. Lines saved after the change use the new ratio, and an older line is converted again only when someone edits its quantities. Before correcting a wrong ratio, check open documents that use the unit, because editing them will recalculate their quantities with the new ratio.

Can a ratio be less than 1?

Yes. A ratio is the number of base units in one of this unit, and it may be a fraction. With a case as the ratio-1 unit and pieces at 0.025, one piece is stored as 0.025 of a case and priced off the case price. Ratios keep up to six decimals, and xMatix keeps enough decimals on the line quantity to hold the finest ratio even if the item's precision is lower.

Does a SKU-specific unit restrict document lines?

No. Document lines accept any of the item's units for any SKU. The SKU on a unit row is read only by order capture, which offers that unit only when the captured line is for that SKU. If a unit should apply to all variants, leave SKU empty.

Related topics

• Items (the item master)
• SKUs (item variants)
• Item aliases
• Item Unit Of Measure — entity reference
• Item — entity reference