Skip to content

POS ​

The POS (Point of Sale) module is Lubb Business'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.
  • Keep selling when the internet is down. The register carries on from what it has stored on the device, saves each sale, and posts it by itself when the connection returns — see Selling offline.
  • 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.

Selling offline ​

The register keeps working when the connection drops, and posts what it sold when the connection returns.

What happens

  • While online, the register keeps on the device everything it needs to sell: the till and its open session, the catalogue with each item's stock, every rate the till quotes, the payment methods, the VAT rate and the customers. It refreshes them as it goes (stock every five minutes, prices every ten).
  • Take a sale with no connection and it is saved on the device under its own number (OFF-00001). A provisional receipt can be printed from the sale screen; the tax invoice is the one issued once the sale is recorded. The register shows an Offline chip and a banner, and counts the sales waiting.
  • When the connection returns the sales are posted automatically, oldest first, each on the day it was rung up. The invoice carries a note: Offline sale 3d982c3a: rung up at 2026-10-23 03:16 by Ahmed. If the till's clock is wrong (a date in the future, or more than 35 days back) the sale is booked today and the note says what the clock read.
  • A sale is posted once, however many times the device sends it. Each carries a reference, and the server answers a repeat with the first result — so a connection that dies after the server booked a sale but before the answer arrived cannot book it twice, and two browser tabs open on the same till cannot either.
  • The stock figure shown offline is the branch's last count less what this till has sold offline since, and the register still refuses to sell more than that.
  • A till or tablet that is restarted during an outage reopens the register from the device. (A small service worker keeps the app's files; it is registered the first time the register is opened, and it never handles API requests.)

What still needs a connection

  • Opening and closing the till. The cash-up is worked out from the books, so Close Till is also held while offline sales are waiting to be recorded; open the till while connected and you can then sell through an outage.
  • Refunds and returns.
  • Paying short. A short payment needs an administrator to approve it online, so offline the full amount must be taken.
  • A customer's own price list. Offline, items are quoted at the till's price list; a price agreed with a customer for an item is still honoured, and a customer who has a price list of their own is flagged with a warning when picked.

When the server refuses an offline sale (the stock was sold elsewhere meanwhile, the till was closed, a payment method was switched off…) the sale is not lost: it waits in the Offline sales list — opened from the chip — with the server's reason, and the chip says N sales need attention. From there a person can Try again (for example after stock is received; the sale then goes to the till's current open session), Approve… a short payment, or Discard it, which records nothing and takes no stock off, so it is only for a sale already dealt with another way.

Good to know

  • Waiting sales are stored in the browser on that device. Clearing the browser's site data, or switching device or browser, loses the ones not yet recorded; the chip is the sign that something is still waiting. Signing out keeps them.
  • A sale is posted into the books it was rung up in. On a site with several organisations, switch back to that organisation for its waiting sales to be sent.
  • If the server stops part-way through an offline sale (an invoice exists but a payment step failed) the sale is held for review instead of being sent again, so it can never be booked twice; cancel the invoice and the sale can be tried again.

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.
  • PosOfflineSale (pos_offline_sale) — the server's memory of a sale sent with a client_ref: claimed before the sale is posted, done with its result once it is (so a repeat gets the same answer), or review if it stopped part-way. The unique reference is what makes an offline sale post once.

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):

MethodPathPurpose
GET/pos/profilesList 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/openOpen a new session on a till with counted opening balances
GET/pos/session/{session_id}/close-previewPreview cash-up reconciliation (expected vs. opening per payment method) and running totals before closing
POST/pos/session/{session_id}/closeClose 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/checkoutRing up a sale — create and post the invoice plus split-tender payment entries (or a return, via is_return/return_against_id). With a client_ref the sale is posted at most once (a repeat returns the first result; 409 sale_in_progress means ask again shortly, 409 sale_needs_review names an invoice a person must check); sold_at books an offline sale on the day it was rung up
GET/pos/receipt/{invoice_id}/pdfRender a sale's receipt as PDF
GET/pos/mode-of-paymentList all payment modes (for the tender picker)
GET/pos/prices?pos_profile_id=Every rate the till quotes in one call (walk-in rates, prices agreed with a customer, and the customers who have a price list of their own), kept on the device to price a sale offline

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.

Lubb Business Documentation