NutraSoft food manufacturing ERP software
Esc
  • GuideGetting startedThree steps to your first call and your first order, then the two shapes every response takes.
  • GuideAuthentication and keysBearer keys, test and live environments, rotation without an outage, and what each scope grants.
  • GuideTest modeA second NutraSoft account of your own, seeded with realistic data, that you can safely break.
  • PageErrorsEvery error code the API returns, what it means, what to do about it and whether to retry.
  • PageConventionsThe rules every operation follows: money, time, paging, sorting, nulls, PATCH and identifiers.
Menu

Units and quantities

Every quantity names its unit, because the underlying numbers genuinely differ. How to convert between them.
Updated

In short

  • Every quantity names its unit: base, display, the line's unit, the purchase unit or grams.
  • Lots are always in base units (quantity_base). Purchase order and bill lines are in purchase units.
  • An inventory unit needs both factors: quantity_base / (uom_qty * uom_base_conversion).
  • Never multiply quantity_base by a purchase cost. The result has no meaning.

A NutraSoft product is counted in more than one unit: a base unit for stock, the unit people see, the unit it is sold in and the unit it is bought in. The API never makes you guess which one a number is in. A partner who assumes one unit throughout computes numbers that are wrong by a conversion factor and still look plausible.

The units

UnitWhere you see itWhat it is
Basequantity_base, order_qty_base, step quantity_baseThe product's base unit, the canonical stock unit.
Displayproduction_qty_display_units, produced_qty_display_unitsThe unit a person sees for that product in NutraSoft.
Line unitorder_qty on sales order linesThe unit the line's uom_type names.
Purchasequantity and cost on purchase order and bill linesThe unit you buy the product in, often a case or a drum.
Gramsportion_in_grams, recipe_grams_yieldGrams.

Where they differ

  • Lots are base units, always. Product lots take and return quantity_base, with no conversion in either direction: what you send is what is stored.
  • Purchase order and bill lines are written in purchase units. quantity and cost are per purchase unit, and purchase order lines also return quantity_base. Multiplying quantity_base by cost gives a number with no meaning; this is the most common unit error.
  • Production runs mix two units. The planned production_qty_display_units is in display units, while planned_steps and consumed_steps quantities are in each component's base unit.
  • Sales order lines carry both. order_qty is in the line's uom_type and order_qty_base is the same quantity in base units. A line's price is per unit of its uom_type.

Converting

Products and lots carry two conversion factors, uom_qty and uom_base_conversion. How many base units one unit holds depends on uom_type:

uom_typeBase units in one unit
BASE_UOM1
INVENTORY_UNITuom_qty * uom_base_conversion
PACKAGING_SIZEuom_base_conversion
text
base_quantity      = quantity * base_units_in_one_unit
inventory_quantity = quantity_base / (uom_qty * uom_base_conversion)
Inventory units use both factors, not one. uom_qty is often 1 in test data and something else in production, so a converter that uses only uom_base_conversion looks correct until it meets a real catalog. A missing factor counts as 1.

Writing sales order lines

Send order_qty in the unit uom_type names; it defaults to BASE_UOM. NutraSoft converts it to base units with the product's factors at the moment the line is written, exactly as the NutraSoft order form does, and the response returns both order_qty and order_qty_base. A later change to the product's factors does not rewrite existing lines.

Money follows the same rule as quantities: a price or cost is per the unit next to it. Scales, rounding and currency are in Conventions.