Guide
Barcode inventory that survives the real stockroom.
From product creation to quantity patch and barcode append — what each screen writes, why remaining slots matter, and what to do when a scan fails. Written for Owners and Workers using /dashboard/owner/products and /dashboard/worker/products.
When to use this guide
Use it when you set up a new business, receive new stock, or need to explain to workers why a SELL fails. It answers: what is a product barcode vs a unit code, how does quantity differ from barcode count, and why night-shift pricing exists.
Step 1 — Create the product correctly
Owners create products from Products → New Product. Required fields: name, category (Alcohol / NonAlcohol or custom), price, stockQuantity. Optional: returnableEnabled/Price, nightShiftEnabled/Price and window. The backend returns a product with remainingBarcodeSlots = stockQuantity − barcodeCount.
- Choose a clear name: "Castle Lager 500ml" not "Beer".
- Set price to the day price. Use nightShiftPrice only if the business charges differently after hours.
- Leave productImageUrl empty if you have no photo — the UI shows a fallback rather than a broken image.
Step 2 — Assign barcodes or unit codes
POST /api/products/{id}/barcodes appends barcodes. Each entry is a physical unit's saleable barcode. The platform also stores a unit code for internal tracking. GET /api/products/barcode/{barcode} resolves a single scan to its product.
Rule you can rely on
SELL transactions require barcodes.length === total quantity across items. BUY transactions must not send barcodes. The API enforces it; the UI shows a clear inline error before submission.
Step 3 — Quantity changes are patches, not overwrites
Stock corrections use PATCH /api/products/{id}/quantity. This keeps a ledger entry rather than silently mutating inventory. Owners see the movement in Reports → Product Movement.
Troubleshooting
“Barcode not found”
Verify the scan actually hit the unit barcode, not the outer case code. Use the worker barcode lookup page to test the scan in isolation before checking out.
Sell fails but quantity is available
Count barcodes scanned vs item quantities. One missing barcode out of 5 units fails the whole checkout — the design prevents untraceable sales.
Night price not applying
Check nightShiftEnabled and that the server time window includes the current sale time. The flag is Pro-plan aware and backend-locked if the plan doesn't support it.
Related reading
- QR Ticket operations manual — capacity and gate scan parallels.
- Worker tips & payouts — what happens after the transaction commits.
- All features — who uses inventory screens by role.
Quick checklist
- Name and category are accurate
- Day price and optional night price are set
- stockQuantity equals physical units on hand
- Every unit has a barcode scanned and saved
- Test one SELL and one BUY before going live
Don't invent barcodes
Copy the printed barcode exactly. A mistyped code creates a unit that can never be scanned at the till — it will block SELL checkout until corrected.