Warehouse operations

Run scan-first warehouse tasks with bin-level balances and one shared movement ledger.

Last updated:

Use Warehouse as the operational home for mobile inventory work.

Entry point

  • Warehouse home: /inventory/warehouse
  • Warehouse home separates:
    • a full-screen Warehouse mode shell instead of the normal desktop header and sidebar
    • Floor operations for the dedicated Warehouse task shell
    • Inventory management pages for opening the standard desktop Inventory screens when setup or review work is needed
  • Warehouse home prioritises:
    • a compact hero with:
      • Scan now primary action
      • a short helper line
      • quick action chips underneath
      • the current working location summary in the same top panel
      • a Change location action once a working location has been selected
    • a Warehouse setup checklist card for first-run rollout:
      • label bins first
      • relabel existing stock with internal labels
      • mark Warehouse ready
    • a matching Prepare Warehouse step in Getting started that opens the Warehouse setup checklist from the wider onboarding journey
    • Scan now as the primary action
    • Continue task using the last Warehouse task opened in this browser
    • Current location as the working-site context for new Warehouse tasks
    • Needs attention for low-stock review and issue reporting
  • Warehouse pages use a dedicated bottom nav for:
    • Home
    • Tasks
    • Scan
    • Attention
    • Exit
  • the label print view opens inside the same Warehouse mode shell on screen, but browser print output removes the app chrome
  • Task routes:
    • /inventory/warehouse/tasks/lookup
    • /inventory/warehouse/tasks/receiving
    • /inventory/warehouse/tasks/putaway
    • /inventory/warehouse/tasks/moves
    • /inventory/warehouse/tasks/counts
    • /inventory/warehouse/tasks/adjustments
    • /inventory/warehouse/tasks/replenishment
    • /inventory/warehouse/tasks/returns
    • /inventory/warehouse/tasks/quarantine
    • /inventory/warehouse/tasks/labels
    • /inventory/warehouse/tasks/issues

What Warehouse is for

Warehouse is the task-first operational workspace for:

  • item, bin, and location lookup
  • goods receiving into a chosen bin
  • putaway from staging into storage bins
  • bin-to-bin stock moves
  • replenishment from reserve/bulk bins into pick-face bins
  • cycle counts and spot checks on a specific bin
  • stock adjustments with explicit reason codes
  • returns restock into a specific bin
  • quarantine moves into a physical quarantine bin
  • relabelling and barcode/bin label print jobs
  • issue reporting with optional image upload

Balance and movement rules

Warehouse tasks now use one shared inventory execution layer:

  • inventory_balance is the authoritative on-hand balance by:
    • customer_id
    • stock_id
    • location_id
    • bin_id
    • optional lot_code / expiry_date
  • inventory_movement is the append-only ledger for every receipt, putaway, move, replenishment, return, quarantine move, adjustment, and count variance.
  • stock.quantity_on_hand is now treated as a summary derived from the balance ledger.

This means bin-level putaway, replenishment, counts, quarantine, and returns all write through the same movement engine instead of separate ad hoc tables.

Scan-first expectations

Every task screen is built around scan-first input:

  • resolve an internal barcode first, then manufacturer barcode, with SKU as manual fallback only
  • resolve a bin code
  • confirm quantity
  • record lot/expiry when needed
  • submit one inventory-safe transaction
  • move through a guided step-by-step flow instead of a full desktop form
  • keep a live progress summary visible while the task is in progress
  • use a sticky action footer for the current next action
  • receive strong success and error scan feedback as each scan resolves
  • use a camera scan button beside scan fields on supported mobile browsers
  • keep Warehouse as the app mode and Location as the physical site where the user is working

Warehouse web officially supports this scanning order for floor work:

  1. Bluetooth HID scanner as the primary path
  2. iPhone camera scan as the fallback path
  3. Manual typing as the fallback path

Recommended phone setup:

  • smartphone
  • paired Bluetooth scanner in Basic/HID keyboard mode
  • correct keyboard layout on the scanner
  • Enter suffix enabled after each scan
  • scan fields keep autocorrect, autocapitalisation, and spellcheck disabled so HID scanner input lands cleanly in the focused field

Warehouse location context follows these rules:

  • if a task is launched from assigned work, the task inherits that location
  • otherwise Warehouse reuses the last selected working location
  • if no location is known yet, the first scanned bin or location can set it
  • for location-sensitive tasks, if the location is still unknown, Warehouse requires the user to return to Warehouse home and choose a working location before the task can continue

Warehouse task pages keep a compact task header and the same bottom nav so the Warehouse area behaves like a dedicated mobile workspace rather than a set of standard Inventory forms.

Task headers show the current working location only. Location changes happen on Warehouse home, not inside individual task screens.

For existing stock with only manufacturer EAN/UPC labels, the recommended first Warehouse rollout is:

  1. print and apply bin labels
  2. run an initial existing stock relabelling pass
  3. apply internal stock labels to the physical stock containers
  4. then use Warehouse mode for day-to-day floor work

Warehouse scan resolution follows this precedence:

  1. internal barcode
  2. manufacturer barcode
  3. SKU fallback
  4. bin code
  5. location code

Internal barcodes are unique per customer so one scan always resolves to one stock item. Manufacturer barcodes can repeat when multiple stock records refer to the same retail release or supplier code.

Warehouse label tasks print the stock item's internal barcode and bin labels print the bin code. Both label types render as Code 128. Manufacturer barcode fields remain product-level identity data and are not used as the warehouse label identity. The standard stock-item edit form keeps internal barcode read-only after first save so warehouse labels remain trustworthy.

Current scope note

Bin-level on-hand is authoritative in Warehouse.

quantity_allocated remains a stock-level summary in v1, so bin-level reserved quantities are not yet assigned by allocation logic. inventory_balance keeps a quantity_reserved field ready for that later step, but current warehouse task flows only mutate on-hand stock.