POS

The POS (Point of Sale) module is Lubb ERP's retail till workflow: a cashier-facing "New Sale" screen for ringing up walk-in sales, a shift-based cash-up (Z-report) process, and admin-configured till profiles that control which company, warehouse, customer, payment methods and items each till can use. It's used day-to-day by counter/retail staff (the lowest operational role tier — "sales") and configured by admins; POS sales themselves are ordinary Sales Invoices under the hood, so they show up alongside every other invoice in Accounting's reporting and Debtors ageing.

What you can do

• Configure one or more POS Profiles ("tills") — each tied to a company and (optionally) a warehouse, a default walk-in customer, a restricted list of allowed payment methods, and a restricted list of allowed item groups. An empty restriction list means "everything is allowed." Tills can be disabled without deleting them.
• Open a till session for a shift, recording the counted cash float per payment method at start of day.
• Browse a till's sales catalogue — only active, sellable items, filtered to the till's allowed item groups if any are set.
• Ring up a sale: add items to a cart, pick a customer (or fall back to the till's default customer), split payment across multiple tender types (cash, card, EFT, etc.), and submit.
• Print, view, or email a PDF receipt for a completed sale.
• Process a return/refund against an original sale (a negative-value sale linked back to the original invoice).
• Preview the cash-up reconciliation at any point in a shift — expected cash/tender totals per payment method versus what was opened with.
• Close a till session (Z-report): enter the counted amount per payment method, and the system records the opening, expected and counted amounts plus the over/short difference for each, along with the shift's total sales count, quantity, net and grand total.
• Review a read-only audit trail of every past POS Session (till, cashier's shift status, opened/closed times, sales count, grand total, and the full Z-report cash-up breakdown).

Common tasks

1. Set up a till As an admin, open POS Profiles and create a new till: give it a name, company, warehouse, default customer (used when no specific customer is picked at checkout), and optionally restrict its allowed payment methods and item groups. Leave a restriction list empty to allow everything.

2. Start a shift From the POS sell screen, pick the till. If it has no open session, open one and enter the counted cash float for each payment method you're starting with. A till can only have one open session at a time — you can't open a second session on a till that's already open.

3. Ring up a sale With a session open, browse the till's catalogue and add items to the cart. Pick a customer (or leave blank to bill the till's default customer). Enter one or more tender lines (e.g. part cash, part card) and submit. This creates and posts a Sales Invoice tagged to the till, plus one Payment Entry per tender line; if the tendered total is less than the invoice's grand total, the shortfall is left as a balance owing on the customer's account rather than blocking the sale. A receipt PDF can then be printed, viewed or emailed.

4. Process a return Ring up the return the same way as a sale, flagging it as a return and referencing the original sale's invoice. This posts a linked credit-note-style invoice against the original.

5. Cash up at the end of a shift Before closing, pull the close preview to see, per payment method, the opening float and the expected amount (opening + everything taken through that method during the shift). Count the actual cash/tenders in the till, then close the session with those counted amounts — the system stores the opening, expected, counted and difference (over/short) for each payment method, plus the shift's total invoice count, quantity sold, net total and grand total. Once closed, the session is locked and shows up in the read-only session history for audit.

6. Audit past shifts As an admin, browse POS Sessions to see every till's shift history — status, opened/closed timestamps, sales count, grand total and the full Z-report breakdown per session — without being able to edit or delete the record.

Data model

POS deliberately adds only two new tables; a sale itself is not a separate document type but an ordinary Accounting document, tagged for POS reporting.

• PosProfile (pos_profile) — a till's configuration: company, warehouse, default customer, allowed payment-method IDs and allowed item-group IDs (both plain JSON lists, empty/null = unrestricted), and a disabled flag.
• PosSession (pos_session) — one open→trade→close lifecycle for a till: which profile, company and cashier (user) it belongs to, its status (open/closed), opened/closed timestamps, the opening cash float per payment method, and — once closed — the closing Z-report (opening/expected/counted/difference per payment method) plus snapshot totals (invoice count, net total, grand total, total quantity). A session has no accounting impact of its own; it's a reconciliation snapshot over payments the till's sales already posted.

Everything else rides on the existing Accounting module rather than duplicating it:

• A POS sale is an AccSalesInvoice/AccSalesInvoiceItem, created and posted through the same document pipeline as any other sales invoice, with two soft (no-FK) columns added onto the existing table: is_pos and pos_profile_id (plus return_against_id for returns). These sales are visible in and reported on by the regular Sales Invoices grid alongside non-POS invoices.
• Each tender line at checkout is an AccPaymentEntry (Receive), one per payment method used, also tagged with pos_profile_id. Payments post on-account (no per-invoice allocation) — a short tender leaves a balance owing on the customer, matching how payments work everywhere else in Accounting.
• Item stock/pricing comes from the existing AccItem/AccItemGroup masters and the till's warehouse; there's no separate POS-owned product catalogue.

Configuration & integrations

• Payment methods are the same AccModeOfPayment records used across Accounting (Cash, Card, EFT, etc.) — a till can be restricted to a subset of them, but the module has no built-in card-terminal or payment-gateway integration; tendering by card/EFT/etc. is recorded manually against whichever mode of payment the cashier selects, the same as any other payment entry.
• Item availability is controlled per till via the allowed item-group list on the POS Profile.
• Receipts are generated server-side as PDF (the same rendering path used for regular Sales Invoice PDFs).
• The POS app itself is access-gated per site/user (an app-level permission check), and every POS route additionally requires at least the "sales" role — the lowest operational tier, matching a cashier's daily access.

API reference

The cashier-facing sell screen and till-session lifecycle are served by dedicated endpoints under /pos (not generic grid CRUD, since a cart/checkout workflow doesn't map to a create-form):

Method	Path	Purpose
GET	/pos/profiles	List active (non-disabled) POS Profiles for the till picker
GET	/pos/session?pos_profile_id=	Get the currently open session for a till, if any
POST	/pos/session/open	Open a new session on a till with counted opening balances
GET	/pos/session/{session_id}/close-preview	Preview cash-up reconciliation (expected vs. opening per payment method) and running totals before closing
POST	/pos/session/{session_id}/close	Close a session, recording counted balances, differences and final Z-report totals
GET	/pos/catalogue?pos_profile_id=	List sellable items for a till, filtered to its allowed item groups
POST	/pos/checkout	Ring up a sale — create and post the invoice plus split-tender payment entries (or a return, via is_return/return_against_id)
GET	/pos/receipt/{invoice_id}/pdf	Render a sale's receipt as PDF
GET	/pos/mode-of-payment	List all payment modes (for the tender picker)

Till configuration and session audit history, on the other hand, are exposed as standard admin grids:

• pos-profiles — full CRUD (create/edit/delete) over PosProfile, admin-only.
• pos-sessions — read-only listing over PosSession (no create/edit/delete), admin-only, sorted by most recently opened — the audit trail described under "Audit past shifts" above.