Billing & POS

The Ezvento POS module is the primary interface for cashiers and billing staff. It supports fast checkout via barcode scanning, product search by name/SKU, touch-friendly quantity controls, and real-time GST calculation. The POS is designed to work offline-first where possible, with automatic sync when connectivity is restored. All transactions are tenant-isolated and tied to the active shift and counter for complete audit trails.

When a cashier logs in, they must select a Counterbefore they can start billing. A counter represents a physical POS terminal (e.g., "Counter A", "Billing Desk 1"). The cashier then opens a Shift which ties all subsequent transactions to that counter and session. This ensures accountability and enables per-counter revenue tracking.

Every cashier session is bound to a Shift record that tracks opening cash, closing cash, expected cash, and variance. The shift model is the foundation of cash accountability and end-of-day reconciliation.

Shift Status Enum

Cash Drawer Transactions

During a shift, every cash movement is recorded as a CashDrawerTransaction. Types include SALE_CHANGE (change given), CASH_REFUND (cash returned for overpayment), CASH_IN / CASH_OUT (float adjustments), and DENOMINATION_EXCHANGE (breaking large notes without affecting drawer total).

The POS cart supports multiple ways to add products: barcode scanning, SKU search, name search, and category browsing. Each line item captures quantity, unit price, discounts, and GST. The cart can be held and resumed, enabling cashiers to serve multiple customers simultaneously.

Ezvento supports two levels of discounting: line-item discounts and bill-level discounts. Both are governed by permission checks and configurable maximum limits per role. Exceeding the discount limit triggers the Manager PIN Approval workflow.

Discount Limits & Manager Approval

Each role has a configured maximum discount percentage. If the cashier attempts a discount exceeding their limit, the system blocks the action and requires a manager to enter their PIN via the ApprovalRequest workflow. The approval permission isDISCOUNT_EXCEED_LIMIT.

In special cases (damaged packaging, clearance, or negotiated B2B rates), a cashier may need to override the selling price of a product. This is a high-risk action and always requires the PRICE_OVERRIDE permission plus Manager PIN approval. The overridden price is recorded in the invoice item and flagged in the audit log with severity WARN.

Each store configures its accepted payment methods via the StorePaymentConfig model. The cashier sees only enabled methods, reducing checkout errors. Mixed mode allows splitting a single bill across multiple payment types (e.g., ₹500 cash + ₹1500 UPI).

Supported Payment Methods

GST is auto-calculated from each product's gstRatefield. The system splits the total GST into CGST and SGST (or IGST for inter-state) based on the store's state and customer's state. The calculation happens at the line-item level and is aggregated on the invoice.

Invoice Types

TAX_INVOICEis used for B2B transactions where the customer's GSTIN is collected.RETAIL_INVOICE is the default for B2C walk-in customers.PROFORMA_INVOICE and QUOTATION do not affect inventory or accounts.CREDIT_NOTE and DEBIT_NOTE are used for post-sale adjustments.RESTAURANT_BILL includes KOT items and table details.

When the cashier completes payment, the system creates a SalesInvoice record along with SalesInvoiceItem rows and Payment rows. The invoice is immutable after creation — any corrections must be done via returns or credit notes.

PaymentStatus Enum

Immutability Guarantee

Once an invoice is created, its items and totals cannot be edited. This is enforced at the database level (no UPDATE endpoints for invoice fields) and at the UI level (read-only invoice view). Any mistakes are corrected via the Returns workflow, which creates aSalesReturn and reverses stock and payments.

Returns are processed against an existing SalesInvoice. The cashier selects the invoice, chooses the items to return, and specifies quantities. ASalesReturn record is created with linked SalesReturnItem rows. Stock is automatically returned to inventory, and payments are reversed based on the original payment method.

Refund Permissions

Processing a return requires SALE_REFUND permission. If the refund amount exceeds a configured threshold, manager PIN approval is required via thePAYMENT_REFUND permission. Refunds to UPI/card are initiated through the payment gateway; cash refunds are recorded as CashDrawerTransaction.CASH_REFUND.

For GST-registered businesses, Ezvento generates e-invoices via the Invoice Reference Number (IRN) system. The IRN is a unique hash generated by the GST portal that makes the invoice tamper-proof. Ezvento stores the IRN, signed invoice, and QR code on the SalesInvoice model.

IRNStatus Lifecycle

IRN generation is triggered automatically for TAX_INVOICE types when the invoice is created. If the GST portal is unavailable, the invoice is created with irnStatus: PENDINGand a background job retries periodically. Failed IRNs are surfaced in the admin dashboard with the error message for manual resolution.

High-risk cashier actions (cancellations, refunds, excessive discounts, price overrides) require real-time manager approval. The cashier triggers an ApprovalRequest, a manager enters their PIN, and the cashier retries the original action with theX-Approval-Id header. This creates an auditable chain linking the cashier, manager, action, and timestamp.

ApprovalStatus Enum

Ezvento supports multiple printer configurations via the PrinterConfig model. Each printer has a type (RECEIPT, KITCHEN, LABEL), connection method (NETWORK, USB, BLUETOOTH), paper width, and auto-cut settings. The PrintReceipt component formats the invoice data into ESC/POS commands for thermal printers and sends it to the configured default printer.

PrintReceipt Component

The PrintReceipt component takes a SalesInvoice object and formats it into a thermal printer-ready string. It includes the store name, invoice number, date, itemized list with HSN codes, GST breakdown (CGST/SGST), totals, payment method, and a thank-you footer. For kitchen printers, the component generates a KOT-style ticket with item names, quantities, table number, and special notes.

The CameraScannercomponent enables barcode scanning using the device's built-in camera. It uses the browser's getUserMedia API to stream video and a barcode detection library to read EAN-13, UPC-A, Code 128, and QR codes. When a barcode is detected, it is emitted as an event that the POS cart consumes to add the product.

The client-side POS state is managed by a Zustand store with persist middleware. This ensures that cart contents, shift data, and customer selection survive page refreshes and browser crashes. The store is partitioned into slices for cart, shift, and customer state.

Persistence Strategy

Cart, shift, and customer slices use Zustand's persist middleware withlocalStorage as the storage backend. The persist key includes the tenant ID and store ID to prevent cross-tenant data leakage. On shift close, the cart slice is cleared automatically. If the cashier refreshes the page mid-transaction, the cart is restored exactly as it was.