Products & Inventory

Overview

This feature covers the entire CRUD cycle for merchandise items sold through the POS. It allows business owners to define what they sell, what it costs them, and how changing stock levels trigger low-stock alerts.

Why it exists

To run a successful shop, an owner must know exactly what inventory they hold. Robust product management ensures the business can automatically calculate profit velocity, stock valuation, and track supplier costs.

User flow

  1. User logs in and visits app/dashboard/products.
  2. They click "Add Product" or use the AI Assistant to import a list from a CSV.
  3. They input the name, selling_price, cost_price, barcode, and current_stock.
  4. Over time, as shipments arrive, they use the "Restock" feature.

UI walkthrough

![Products List Data Table](../../assets/images/products/list-view.png) ![Product Creation Slideout](../../assets/images/products/create-slideout.png)

Backend logic

  • Margin Calculation: Automatically happens inside Server Actions before displaying to owners.
  • Low Stock Thresholds: A CRON job sweeps every night to check if current_stock <= low_stock_alert_level, firing an email notification if true.

Database tables involved

Tenant Schema:

  • Product: Stores all metadata, barcodes, and current stock integer.
  • Category: Categorization tree.
  • InventoryAdjustment: Audit log of whenever a user manually force-updates a stock count.

API endpoints

  • GET /api/products - Returns paginated products table list.
  • POST /api/products - Validates and inserts a new product.
  • PUT /api/products/:id - Updates specific fields.

Permissions / roles

  • Owner/Manager: Can add/edit/delete.
  • Cashier: Read-only (used implicitly via POS).

Edge cases

  • Decimal stock levels are not supported; stock is an Int. For bulk un-boxed goods (like kilos of rice), they should be managed via variants.

Validation rules

  • cost_price cannot be strictly higher than selling_price unless a specific "Loss Leader" toggle flag is manually passed to override the default Zod protection.

Error handling

  • If updating a barcode that already belongs to another product, Prisma triggers a unique constraint violation which Next.js maps to a user-friendly Toast.

Screenshots placeholders

![Barcode Error Screen](../../assets/images/products/error-barcode.png)

Troubleshooting

  • Products completely zeroed out in stock but still appearing on the POS? Check the Is Active toggle.

Related features