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

  • Open Warehouse from the app navigation.
  • 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. This section is collapsed until opened. Each link has a title, description and destination icon, without category or warning badges
  • Warehouse home prioritises:
    • A compact hero without a separate mode badge, 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 expandable checklist for first-run rollout, below floor tasks:
      • Label bins first
      • Relabel existing stock with internal labels
      • Mark Warehouse ready
      • Setup progress is stored per working location, so each warehouse/location can be rolled out independently
      • The setup card shows a three-step progress bar with numbered/current/done markers and action buttons at least 48px high. Setup actions stack when the card is narrow, with wrapping labels so the full button text remains readable
    • 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
    • Last used with an Open [task] link to the last permitted task opened in this browser. This starts a fresh form; it does not restore unfinished entries
    • Current location as the working-site context for new Warehouse tasks
    • Low-stock review for the low-stock count and a separate issue-reporting action. This is not an outstanding-issues inbox
      • The Review warning appears only when low-stock items are flagged. With zero flagged items, the warning is hidden; Low stock, Report issue and the bottom Attention navigation link remain available.
  • Warehouse pages use a dedicated bottom nav for:
    • Home
    • Tasks
    • Scan
    • Attention
    • Exit to leave Warehouse and return to the standard app
  • Home highlights Tasks or Attention when that section is selected.
  • The label print view opens inside the same Warehouse mode shell on screen, but browser print output removes the app chrome
  • Warehouse task areas include lookup, receiving, putaway, moves, counts, adjustments, replenishment, returns, quarantine, Bin labels, Stock labels, and issue reporting.
  • Task headings, including Lookup, use the selected theme's rounded card surface with inset text. The heading and working location remain sticky; Lookup's Scan another action stays in the same header when available.

Permissions and setup state

Warehouse mode is gated separately from general Inventory access:

  • Warehouse view access opens Warehouse home, Lookup and scan results.
  • Warehouse operations access opens receiving, putaway, moves, replenishment, returns, quarantine, and issue reporting.
  • Warehouse adjustment access opens Counts and Adjustments.
  • Warehouse label access opens label tasks, print jobs and label lookup.
  • Warehouse setup access allows the location checklist to be saved.

Home hides floor-task links and setup/label actions that the signed-in user is not permitted to use. Server-side permission checks remain authoritative; hiding a link does not grant or replace access checks. A remembered task that is no longer offered falls back to Lookup.

The Warehouse setup checklist is saved by ChannelWeave, so progress follows the working location rather than one browser tab. Warehouse ready can only be completed once both Label bins first and Relabel existing stock with internal labels are complete.

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 use one shared inventory execution model:

  • On-hand balance is tracked by stock item, location, bin, and optional lot/expiry details.
  • Movement history is append-only for every receipt, putaway, move, replenishment, return, quarantine move, adjustment, and count variance.
  • Stock item quantity is treated as a summary derived from warehouse balances.

This means bin-level putaway, replenishment, counts, quarantine, and returns all follow the same movement rules.

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 only the current step and relevant controls in view
  • Check the selected item, bins, quantity and transaction effect beside the final action
  • Use actions in the page flow, not a second fixed footer overlapping navigation
  • Receive strong success and error scan feedback as each scan resolves
  • Use a prominent Scan with camera button above each operational scan field; Find and manual/Bluetooth entry remain available
  • Keep Warehouse as the app mode and Location as the physical site where the user is working

Warehouse provides these scan-input options for floor work:

  1. Bluetooth HID scanner as the primary path
  2. Camera scan, including an iPhone Safari-compatible decoding path, when camera access is available
  3. Manual typing as the fallback path

Camera scanning and iPhone Safari

Open ChannelWeave over HTTPS in Safari, sign in, then use Warehouse → Scan now. In Lookup, tap Scan with camera and allow camera access for ChannelWeave. Other scan tasks use the same prominent camera action above their scan field. Use the scanner inside ChannelWeave, not the separate Camera app. No Safari experimental feature flags or scanner app installation are required.

The scanner requests the rear-facing camera, uses a muted inline preview, and decodes frames on the device using one pinned, self-hosted ZXing JavaScript decoder. It does not depend on Safari exposing the native BarcodeDetector API. Camera frames are not uploaded; only the decoded text is sent to the existing authenticated, customer-scoped Warehouse resolver. No third-party decoding service is called. Supported configured formats are Code 128, Code 39, Code 93, Codabar, ITF, EAN-13, EAN-8, UPC-A, UPC-E and QR. A readable barcode must still match a stock item, bin or location in the current account.

Keep one barcode and its white margins in view, with the bars upright and the code running horizontally. Avoid glare and move closer if the bars are too small. When a code is captured, the camera closes, the scan field is filled and the existing resolve action runs automatically. In Lookup, the result shows the matched entity; a bin result includes its location, stock lines and quantities, or an empty-bin message. Lookup does not change stock. In write tasks, resolving a scan does not replace the task's later quantity/review/submit steps.

The camera sheet focuses Close, keeps keyboard Tab focus inside the sheet and makes the Warehouse content behind it inert. Closing restores the previous focus and background state. The sheet fits the dynamic viewport with safe-area spacing, and Close stays in a non-scrolling header while the preview and guidance scroll below it on shorter screens. Physical iPhone browser-bar and VoiceOver acceptance remain TODO.

Close, Escape, leaving the page or putting it in the background stops the camera. Reopen it explicitly to scan again. Closing while a permission or video playback request is pending also cancels that attempt; a late response cannot restart it or fill another field.

If scanning is unavailable:

  • A disabled camera button has explanatory text: use HTTPS, check browser camera support, or reload if the decoder could not load.
  • If access is denied, allow Camera for this site in Safari's website settings and tap the camera button again.
  • If no camera is found or it cannot start, close other camera-using apps and retry. Bluetooth HID scanning and manual entry remain available.
  • No match means a code was read but the account's resolver did not find it; it does not mean the camera failed. Check the code and account before retrying.

Verification boundary: automated tests cover decoding generated bin/stock Code 128 pixels and manufacturer EAN/UPC fixtures without BarcodeDetector, permission failures, cancellation, cleanup and single-result handoff. These are not physical-device acceptance. TODO: verify a printed label on an iPhone 13 and record the iOS/Safari versions, rear-camera permission/preview, successful Lookup, denial recovery, and closing/backgrounding behaviour. A screen-displayed barcode is a useful preliminary check, not proof of printed size or scan quality.

Bluetooth scanner setup

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
  • Scan fields are marked as searches with autocomplete disabled to discourage password and verification-code suggestions. Browser or password-manager settings can still override these hints; scanner input and Enter-to-resolve behaviour are unchanged.

Warehouse home and direct task links use the same location selection rules:

  • Load and validate the current account's location list before using a location
  • If a task supplies a location, use it only when it appears in that list. If it is unavailable, ask for a location on Warehouse home rather than silently switching the task to a different site
  • Otherwise reuse a remembered working location only if it is still in the list
  • With no valid remembered selection and exactly one available location, automatically select and remember it. Home shows its name and collapses the picker; direct task links use the same default
  • With multiple locations and no valid selection, ask the user to choose. With no locations, prompt them to add one under Inventory → Locations
  • Failed or malformed location responses leave the working location unset; reload the page to try again. Do not use an unverified remembered location
  • In Lookup, the first scanned bin or location can set the working location only when its location appears in the loaded list
  • 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

Selecting a location only establishes working context and loads its setup state; it does not complete setup steps, mark Warehouse ready, or move stock. Change location remains available. Clear removes the current selection until a new choice or page load; a later page load applies the same single-location rule.

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.

Quick Lookup

Lookup is a compact scan → result → scan again screen for repeated phone use, not a two-step wizard. Its heading shows the working location without a separate location card. It has no task badge, progress bar, step summary, Back/Previous controls or fixed action footer; the usual Warehouse bottom navigation remains.

  • Tap Scan with camera to open the camera. Camera access starts only after a tap, never just by loading Lookup. Loading the page does not focus the code field or bring up the phone keyboard.
  • For manual or Bluetooth HID input, tap Code or SKU and enter/scan the code. Use Find or the scanner's Enter suffix. A lookup already in progress blocks duplicate requests and temporarily disables editing.
  • A match replaces the scan controls with its result. The summary stays compact on phones; stock contents and balances remain below it. Scan another stays in the compact sticky header while the result scrolls, rather than in a large panel covering the content.
  • Scan another clears the previous result and preserves the working location. After a successful camera lookup, that tap immediately reopens the camera. After a typed/Bluetooth lookup, it clears and focuses the code field instead. Closing the reopened camera leaves the normal scan/manual controls available.
  • Unmatched codes or failed requests show an error with the scan controls still available, not a stale result. Camera permission failures retain manual input.
  • Bin contents show item/SKU and on-hand quantity together without horizontal scrolling. Find stock in this bin filters the returned contents; Show 50 more reveals additional rows. Only 50 rows are rendered initially, but the resolver still returns the complete bin contents: this is not server-side pagination. Lot, expiry and reserved quantities expand per row. Trailing decimal zeroes are removed without rounding non-zero fractional quantities.
  • Scanning help expands the barcode priority and Bluetooth setup guidance; it is collapsed during normal use.

Lookup remains read-only for inventory. Other Warehouse tasks retain their existing quantity, review and submission steps. Automated tests cover repeat input, camera handoff, request locking and error recovery; a fresh physical phone walkthrough is still needed for iPhone camera/keyboard acceptance.

Operational task steps and confirmation

Receiving, putaway, moves, counts, adjustments, replenishment, returns, quarantine and issue reporting use compact guided steps:

  • The task title and working location stay in a compact header. Task help holds longer instructions; the progress rail and repeated live-summary cards have been removed.
  • The current step counter, instruction and controls are shown together. Scan success and error feedback appears here, not above a large page header.
  • Scan steps have one camera action and a Find action for typed/HID input. Previous and subsequent actions remain in the document flow above the bottom navigation; they do not cover the fields or results.
  • The final step shows a Check before confirming summary with the selected item, source/destination or counted bin, quantity, relevant reason/type, and any entered lot, expiry or note. Optional lot/expiry/notes are expandable. Counts record the counted amount and adjust by variance; adjustments state add/remove; moves preserve total on-hand; receipts/returns add stock; issue reports do not change quantities. The summary is not a reservation or a promise that server validation will succeed.
  • Enter resolves a scan or advances an intermediate step. It does not confirm the final transaction. Use the explicit confirmation button. While the request is pending, repeat confirmation taps are blocked; errors retain the entries for correction/retry.
  • Choosing another page after editing a movement/issue form offers Keep working or Discard and leave. A browser reload/close may also show the browser's own warning, subject to its support. This is not draft storage: returning through Last used opens a fresh form, and closing or losing a tab can still lose unsaved work.
  • Controls retain 48px minimum touch targets. Missing working locations still gate location-sensitive tasks before stock can be submitted.

Bin labels and Stock labels

Labels use two separate, compact forms rather than a step-by-step wizard:

  • Bin labels (/inventory/warehouse/tasks/bin-labels): choose an existing bin from the current working location. You do not need to scan an existing label to print the first one. A working location and a bin with a code are required; if none are available, create a bin in Inventory → Bins first.
  • Stock labels (/inventory/warehouse/tasks/stock-labels): scan an internal or manufacturer barcode, or enter a SKU, then choose Find stock. A scanner's Enter suffix also resolves the item. Check the displayed SKU and stock name before proceeding. Changing the search clears the selection and requires a fresh lookup. Stock labels identify the stock item, not a particular bin.

Both forms default Label copies to 1, accept 1–50 whole copies, and offer optional notes. Preview labels creates the shared label print job and opens its print setup; choose a physical format, then create an actual-size PDF. Return to the matching label form to change the item or quantity. Creating a stock-label preview assigns an internal barcode if the item does not already have one. Printing labels does not change stock quantities, move stock, assign it to a bin, or mark setup steps complete.

Warehouse home has separate task tiles for both forms. The setup checklist's Print bin labels and Print stock labels links open the matching form directly. The combined /inventory/warehouse/tasks/labels page is no longer a route.

Physical label formats and printing

There is no single label size or printer required by ChannelWeave. Bin labels and Stock labels have distinct layouts, with shared physical-format controls:

  • Roll labels: one PDF page per label, at the exact specified width and height. Presets are 100 × 50 mm (the initial bin default), 60 × 40 mm (the initial stock default), 50 × 25 mm, and 4 × 6 inches (101.6 × 152.4 mm).
  • A4 sheets: labels are positioned by their dimensions, rows, columns, margins and gaps on a 210 × 297 mm portrait page. A 21-label preset uses 63.5 × 38.1 mm labels, three columns, seven rows, 7.25 mm left margin, 15.15 mm top margin and 2.5 mm horizontal gaps. Match these measurements to the packaging; this is not a promise of compatibility with a branded template.
  • Custom formats: change width, height and inside padding. For A4, also set the sheet geometry. Dimensions are in millimetres. The supported label bounds are 25–210 mm wide and 25–297 mm high, with 1–10 mm inside padding; the requested text and barcode must still fit.
  • Printer resolution: select 203, 300 or 600 dpi to match the printer. Barcode module widths use whole dots at this resolution. The driver still controls the physical printer and its printable area.

The everyday print controls show Label stock, Printer resolution and a concise format summary. Advanced settings holds dimensions, padding and sheet geometry. Selecting a custom format or A4 sheet opens it; A4 includes First unused position, also shown in the format summary. Native validation opens hidden advanced fields when they need correction.

The bin layout has a prominent bin code, current location, optional note and barcode. The stock layout has the SKU, stock name, optional note, internal barcode and its human-readable value. Labels are black on white, independent of app theme. PDFs contain no app navigation, job summary or explanatory report.

A successful format is saved in this browser's local storage, separately for Bin labels and Stock labels. It is not an account-wide printer setting, does not save customer or stock identities, and is not shared with other browsers or workstations. Blocked browser storage does not prevent printing.

  1. Choose the format and, for a partly used A4 sheet, First unused position. Positions run left-to-right across each row, starting at 1 in the top-left. Only the first page skips used positions. The start position is never saved.
  2. Choose Print a test label. This creates a one-label PDF from the same job and layout without changing the job's quantity or marking anything printed.
  3. Use Open PDF & print or Download PDF. In the PDF viewer, select the matching paper size, Actual size / 100%, and one copy. Do not use Fit to page or print the setup webpage itself.
  4. Measure the test, check its alignment and scan it into Warehouse Lookup. Confirm the expected entity before using Create label PDF for the full quantity. After an A4 test, advance the first unused position before the batch. Re-feed a partial sheet only when the printer and stock manufacturer allow it.

Print and PDF action buttons have centred text and wrap as needed on narrow screens, while retaining a minimum 48px touch height.

Changing the format clears the ready PDF link: generate a new PDF before printing. A previously opened or downloaded PDF remains unchanged.

The renderer preserves ten-module quiet zones and rejects barcode modules below 0.25 mm or barcode height below 10 mm. These are application layout safeguards, not scanner certification. It also refuses overflowing text or glyphs absent from the embedded Inter font rather than clipping, substituting characters or silently shrinking the barcode. A long code/name/note may need a larger label; 50 × 25 mm works only for suitably short content. Inter does not cover every writing system. Unsupported characters currently block the PDF with an explicit error; broader font coverage is not claimed.

Before each PDF is generated, Warehouse checks within the current account must resolve the stored barcode to the same target. Bin codes are unique only within a location, but scanning searches the customer's bins across locations. A bin code repeated at another location, colliding with a higher-priority stock scan, or changed since the job was created cannot be printed through this route. Use a distinct bin code and create a fresh job. The label contract remains the bin code; printing does not introduce a new identity scheme or repair data.

PDFs are read-only outputs. ChannelWeave cannot choose a local printer, verify successful physical printing, calibrate media, or guarantee all driver/hardware combinations. A real printer-and-scanner test remains necessary.

Initial labelling and scan identities

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 Stock-item 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.

Allocation, dispatch, and valuation

Bin-level on-hand is authoritative in Warehouse, and sales allocation reserves specific sellable balance slices. Allocation chooses sellable balance rows in FEFO order: earliest expiry date first, then oldest balance row.

Dispatch consumes the reserved balance slices rather than decrementing only the stock summary. Each dispatched slice records a dispatch movement, reduces the bin-level on-hand quantity, releases the matching reserved quantity, and records COGS from FIFO cost layers.

Inventory → Stock valuation reports remaining stock value from FIFO cost layers. It also flags quantity mismatches between physical balances and cost layers. Each cost layer carries a currency code inherited from the purchase order currency for receipts or the account inventory valuation currency for opening balances, adjustments, returns, and count variances.

The Stock on-hand and allocated totals remain Stock-item summaries for lists, Channels and dashboards. Warehouse activity updates those summaries; the summaries are not a replacement for the underlying movement history.