Units

Product vs. Unit, in one line: a Product is the catalogue entry; a Unit is one tracked item of it.

Looking for measurement units like "lb", "gal" or "ea"? That's Units of Measure.

A unit is one physical item of a Product. If the Product is "Cordless Drill, 18V," then each actual drill — sitting in a bin, checked out to a tech, or in transit between warehouses — is a unit. Units carry their own location, bin, status, optional lot and expiration, and a complete movement history, while inheriting their name, price, and usage type from the Product.

Naming note: these records are Units in the app and in the REST API alike — /api/v1/inventory/units, referenced from other resources as unit_id. Don't confuse them with Units of Measure (lb, gal, ea), which are measurement labels served from /api/v1/inventory/units-of-measure.

Everything you do with stock happens to units: you check them out, sell them, transfer them, mark them used, hold them, and count them. The Product just says what they are.

How units come into being #

Units are created several ways:

• Receiving a purchase order — purchasing creates units as stock arrives, landing them in the location's receiving bin.
• Manually — Inventory → Units → New Unit, useful for opening balances or stock that didn't come through a PO. You can create several identical units at once with the quantity to create field.
• Building from existing inventory — when the Product is composite, creating an unit can consume its component units, which are marked used automatically and linked to the new unit.
• Manufacturing — work orders produce finished units from components.

When you create a unit you choose its Product (required, and it must come first), optional name override, vendor, location and bin, starting status, barcode, and — if the category tracks them — a lot number and expiration date. Pricing can be Each, Total, or Inherit from Product.

Unit statuses #

A unit is always in exactly one status, shown as a badge in the list:

• In Stock — sitting in a bin, available.
• Checked Out — a Returnable unit is out with a person; it has an active checkout record.
• On Hold — reserved for something (an appointment, a sales order, etc.) and not available to others.
• In Transit — moving between locations on a transfer.
• Out of Stock — depleted.
• Discontinued — no longer carried.

Statuses change as a side effect of the actions below — you rarely set them by hand, though a bulk Change Status action exists for corrections.

Actions on a unit #

The actions available depend on the Product's usage type and the unit's current status. From the unit list (or the unit's own page):

• Check Out — Returnable, In Stock only. Hand the unit to a staff user, customer, or contact with an optional due date and notes. Status becomes Checked Out. See Asset Checkout.
• Check In — Checked Out only. Bring it back into a destination bin; status returns to In Stock and the checkout is closed.
• Mark as Used — Consumable, In Stock only. Record a percentage consumed; the unit's remaining quantity drops by that much, and a unit that hits 0% is emptied out of its bin.
• Transfer — move the unit to a different location and/or bin. See transfers.
• Hold / Release — reserve a unit for an appointment or order, then release it back to stock.
• Discard / Donate — take a unit out of inventory with a recorded reason.

Each of these writes a movement (below), so the history always explains how the unit got to its current state.

Bulk actions #

Select multiple units in the list to Bulk Transfer, Bulk Check Out (eligible units only — ineligible ones are skipped with a count), Bulk Discard with a reason, or Bulk Change Status.

Remaining quantity #

Each unit tracks a remaining quantity as a percentage of one full unit — handy for partially-used consumables (a half-full drum reads 50%). The form offers quick-set buttons (100 / 75 / 50 / 25 / 0%) and shows the real amount alongside, computed from the Product's unit size (e.g. 50% × 500 ml = 250 ml). Returnable equipment is tracked whole — it's either out or in, not partially used.

Lots, expiration, location, and bins #

• Lot number and expiration date appear on the unit only when its Product's category is set to track them — keeping the form clean for units that don't need them.
• Location and bin say where the unit physically is. Setting a bin sets the location automatically. In single-location accounts the location field is hidden. Bins are hierarchical, so a bin shows its full path (e.g. Warehouse A → Rack 5 → Shelf 3).
• A bin is required for In Stock units — stock nobody can walk to is not really in stock. Adding stock by hand pre-fills the location's default receiving bin — which every location has, named Receiving, from the moment it is created — and changing the location re-points it at that location's own. So most of the time there is nothing to choose. If the shelf you want does not exist yet, + New Bin on the field creates it at the selected location without leaving the form (subject to the create inventory bins permission). Units that are not in stock (checked out, on order, discarded) need no bin.
• Custom fields inherited from the category appear at the bottom of the form and on the unit's page.

Movement history #

Every meaningful event on a unit is recorded as a movement, visible on the Movements tab of the unit's page. A movement captures the type, the amount and units involved, the source and destination location/bin, and any notes. Movement types include Purchase, Sale, Transfer, Check Out / Check In, Used, Adjustment, Discard, Donation, Return, Material Consumed, and Manufactured. Together they form an unbroken audit trail — nothing changes a unit's location, status, or quantity without leaving a movement behind.

The Checkouts tab shows the unit's checkout history — who had it, when it left, when it came back, due dates, and overdue flags.

Counting and accuracy #

When you reconcile what's recorded against what's physically on the shelf, the adjust action posts the difference as an Adjustment movement so the remaining quantity matches reality and the history stays honest. See cycle counts.

The unit list #

The unit list (Inventory → Units) shows each unit's Product/name, location, bin, status, and remaining %. Filter by category, location, bin, or status, and toggle In stock only to focus on what's actually available.

Doing it from the API #

# List units
curl "https://your-domain.com/api/v1/inventory/units" \
  -H "Authorization: Bearer $TOKEN"

# Check a unit back in to a bin
curl -X POST "https://your-domain.com/api/v1/inventory/units/{item}/check-in" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"bin_uuid": "..."}'