LumenPOS Guide

What LumenPOS is

LumenPOS is a retail till that runs on top of ERPNext. It gives your cashiers a quick, modern selling screen. Search or scan, tap to add, take payment, print. Every sale posts as a normal ERPNext invoice with the right stock and accounting behind it. Nothing is kept in a side system: your inventory, customers, and books stay in ERPNext.

It's designed for real counters, so it also handles the things a shop needs day to day: its own promotions, gift cards, store credit, loyalty points, returns, cash-drawer reconciliation, and selling while the internet is down.

Requirements

• Frappe / ERPNext v13, v14, v15 or v16
• A configured POS Profile with a company, selling price list, warehouse, and payment methods
• Your cashier's user added to that POS Profile (under Applicable for Users)
• Optional: Lumen Reports, for the Insights sales dashboard (see Insights)

That's it. The front end is pre-built and shipped with the app, so you don't need Node.js or a build step to install it.

Installing

On Frappe Cloud (marketplace)

Install LumenPOS onto your site from the Frappe Marketplace, then let the site finish updating. When it's done, open https://your-site/pos.

On a self-hosted bench

cd frappe-bench
bench get-app https://github.com/ma7mod7osam/LumenPOS
bench --site your-site install-app lumenpos
bench --site your-site clear-cache

Then open https://your-site/pos.

cd frontend && npm install && npm run build

First-time setup

1. Create (or open) a POS Profile. In ERPNext, go to POS Profile and make sure it has:

• a Company
• a Selling Price List
• a Warehouse that belongs to that company
• the payment methods you accept (Cash, Mada, Credit Card, etc.)
• your cashier under Applicable for Users

2. Set a default customer on the POS Profile (for example, "Walk-in Customer"). This is what a sale is billed to when no specific customer is chosen, and in Sales-Invoice mode a customer is required, so don't skip it.

3. Open the POS. Go to https://your-site/pos. The first time you open it online, LumenPOS quietly caches your catalogue so search is instant and offline selling works later.

4. Adjust settings (optional). Open Settings inside the POS to configure promotions, price books, receipt design, gift cards, permissions and more. Store-level things like price list, warehouse, taxes and payment methods stay on the POS Profile in ERPNext, which remains the single source of truth.

Making a sale

The sell screen is one page:

• Find products by typing in the search box or scanning a barcode. Scanning a barcode adds the item straight to the cart.
• The cart shows each line, quantity and price, with a badge when a promotion is applied.
• Change quantities or remove lines directly in the cart.
• Park a sale to set it aside (a customer forgot their wallet, say) and Retrieve it later from the top bar.
• Discard clears the cart.

When you're ready, press Pay to go to the payment screen.

Checking a price or stock

The Price check button looks up any item without adding it to the sale. Scan it, or type a name, code or barcode. It shows the live price and the stock here.

If the item is held elsewhere too, tap the all-stores figure to expand a per-branch list with available and reserved quantity, this store first. That answers "do you have it at the other branch?" at the counter instead of over the phone.

Prices and promotions are always worked out on the server when the sale is submitted, so the amount you charge is exactly what the posted invoice shows. No rounding surprises.

Customers

• Add a customer with the "+ Add a customer" button. Search existing customers by name, mobile or tax ID, or create a new one on the spot.
• Create either an individual or a company customer. Company records can carry a tax ID and address for the receipt.
• Picking a customer can activate a customer-group price book, so their pricing updates automatically.

If you create a customer while offline, LumenPOS saves them locally and reconciles on reconnect, matching an existing record by mobile number if one already exists, so you don't end up with duplicates.

Discounts and promotions

LumenPOS has its own promotions engine, so you don't have to wrangle ERPNext Pricing Rules at the till. Create promotions in the desk under POS Promotion → New.

Targeting. A promotion can match by item, item group or brand, or apply to everything. Limit it to certain outlets (POS Profiles) and customer groups.

Scheduling. Run a promotion within a date range, on specific days of the week, and even within a daily time window (happy hour).

Coupon codes. Turn on Requires Coupon Code to gate a promotion behind a code the cashier enters at the till. Codes are unique across active promotions.

Stacking. Promotions marked Can combine stack with each other. Non-stackable ones compete, and the customer automatically gets whichever is worth more. A discount never exceeds the line or basket total.

Nudges. When a cart is one item short of a Buy X Get Y, or just under a Spend & Save threshold, the screen suggests the customer add a little more to unlock the deal.

Taking payment

On the payment screen:

• Choose a tender: Cash, card (Mada, Credit Card), Gift Card, Store Credit or Cashback.
• Split payments across several methods. Quick-cash buttons speed up cash entry.
• Change due is shown for cash over-tender.
• Redeem loyalty points, store credit or cashback if the customer has a balance.

Press Complete Sale to post the invoice. If the sale can't post for any reason, nothing is half-saved. Your cart and entered payments stay on screen so you can fix the issue and try again.

Payment rules (optional)

• Require a transaction reference on a method (Settings → Payment Methods). The payment screen then asks for the terminal or transfer reference, with your own label such as Approval code, and won't complete the sale until it's filled. A disputed card payment can always be traced back.
• Block a method for certain products. Create a POS Payment Restriction to stop, say, gift cards being used on a buy-now-pay-later method. Match by item, item group (including everything beneath it), brand or tag, optionally per outlet. The till greys the method out and says why, and the server re-checks before posting, so a stale tab or an offline sale can't slip past.

The register

LumenPOS treats each shift as a register session so the cash drawer always balances.

• Open the register at the start of a shift and enter the opening float, the cash you start with.
• Cash in / cash out records money added to or taken from the drawer during the shift.
• X-report is a mid-shift read of sales and expected takings, available any time from the top bar. It does not close the drawer or post anything. Any cashier on the till can pull one.
• Close the register at the end of the shift. Count the drawer (a blind count, so the expected figure doesn't bias it), and LumenPOS compares counted vs expected per payment method and produces a Z-report.

Several outlets, one login

If you're assigned to more than one outlet, the Open register dialog has an Outlet picker. Choose which till you're operating and enter its float. Each outlet runs its own independent shift, so a shift open in one branch never blocks another, and you're warned if you still have a register open elsewhere. Managers see every outlet.

Who owns a shift

Under Settings → A shift belongs to you choose:

• The outlet (default). One shift per register, and any assigned cashier can sell on it.
• The cashier. Each person opens their own shift on that register and can only sell on their own. Several people can share one counter while each stays accountable for their own drawer and gets their own Z-report.

Safeguards at closing

• Queued offline sales block the close. They belong to this shift's drawer, so the close screen shows how many are waiting with an Upload now button.
• A stale closing screen is refused. If a sale lands from another till or tab after you opened the closing screen, the figures you counted against are out of date. LumenPOS asks you to refresh and re-check rather than posting a wrong variance.
• A slow or failed end-of-day close never blocks the next shift. The moment you close, the register is free. Consolidation finishes in the background and self-heals.
• Typed amounts are read exactly as typed. 1,500, spaces and Arabic-Indic digits all work, and an unreadable box stops the action instead of silently becoming zero.

Alerts (optional)

• Cash variance. Email a chosen role when a counted amount differs from expected by more than a threshold. It records and notifies, and never blocks the close.
• Forgotten shift. Build a shift schedule (a reusable timetable, including shifts that cross midnight) and attach it to an outlet. LumenPOS emails a role when a register is still open past its shift end, with a grace period. A till is never closed automatically, because a close without a real cash count is worthless.

Locking the till

Turn on the lock screen in Settings and each cashier sets their own PIN (4 to 8 digits) the first time they meet it. Unlocking checks their PIN and is recorded with their name. Forgot your PIN? emails a 6-digit code, valid 15 minutes. There's no shared code and no manager override. The lock screen guards an unattended till, it doesn't authorise anything.

Returns and refunds

• Open History, find the sale, and choose Refund. From a customer's purchase list, Open in History takes you straight there.
• Refund the whole sale or selected lines.
• Split the refund across several methods, useful when the customer paid partly by card and partly in cash. Each line has its own amount and, where the method requires it, its transaction reference. A running "x left to allocate" must match to the cent before the refund can post.
• Refunding is restricted to the methods your refund rules allow (unlike collecting, where any tender is fine), and every line is checked.
• Refunding to Store Credit is a setting. Turn it off if shop policy is money-back only, with one exception: credit the customer actually spent on that sale can always go back to credit.
• A return posts on the outlet handling it, not the one that made the sale, so the money and the returned stock land where they really moved. Returns across different companies are refused.
• The refund posts as a proper credit-note invoice, linked to the register session, so the drawer count stays correct.

Decide what you will not take back. In Settings → General → Returns and refunds you can refuse a return by item, item group (and everything under it), brand or tag, at every outlet or only at some. Each rule is one of two strengths: the product comes back only when an approver allows it, or it never comes back at all. At the till the refund screen marks the line, shows the reason you wrote, and turns the button into a return approval request when one can still help. The server checks again before the credit note posts.

Who may process a return, and who may approve one past the return window, is controlled in Permissions below. An approval request shows the approver what is being returned or discounted, and any request left unconfirmed is voided when the shift closes.

Gift cards, store credit and loyalty

Gift cards. Sell a gift card as a normal sale. It posts to a gift-card liability account, with no tax until the card is spent, then you redeem it later as a payment method. Balances and history are tracked per card.

Store credit. Each customer can hold a store-credit balance, backed by a liability account. It appears as a "Store Credit" payment method and can be topped up by refunds.

Loyalty. LumenPOS uses ERPNext's native Loyalty Program. Assign a program to your customers, directly or via customer group. Points are earned automatically on sales, and the customer can redeem them at the payment screen.

Cashback

Reward customers with cashback they spend on a later visit. Each customer has their own cashback balance, and you decide how it is earned under Settings → Cashback:

• How much: a percentage of the sale or a fixed amount, with an optional cap per sale.
• When it applies: a minimum spend, the products that count (by item, item group, brand or tag, included or excluded), chosen outlets, a customer group, set dates, days of the week and hours, and optionally a coupon code.
• How long it lasts: earned cashback can expire after a set number of days, and can be held for a few days before the customer can spend it.
• Several rules: rules can combine or compete, the same way promotions do.

At the till, the payment screen shows the cashback the sale will earn, and the customer's available balance can be spent with Use cashback. Paying with cashback never earns new cashback on the part it paid for. A refund takes back the cashback that sale earned and the customer has not spent yet, and cashback that reaches its expiry date is removed automatically.

Accounting. Cashback is booked properly in ERPNext. Each company chooses a cashback liability account and a cashback expense account under Settings → General → Company accounts, and both are created automatically if you leave them empty. Earned cashback is booked as an expense against the liability, spent cashback leaves the liability through the sale's own payment, and expired or refunded cashback is reversed. LumenPOS books all of this as one summary Journal Entry per company, day and outlet, not one per sale: every night, or straight away with Book to accounts now in the Cashback tab. Once everything is booked and the shifts are closed, the liability account equals what your customers hold.

Cashback is on by default but earns nothing until you create a rule, and it can be switched off in Settings.

Receipts and printing

You have three ways to print, and LumenPOS picks the best available automatically:

1. Thermal printer (ESC/POS). Configure a printer IP and port on the POS Profile. The Frappe server prints to it directly and can kick the cash drawer. On cloud-hosted sites the printer needs to be reachable from the server. Otherwise LumenPOS falls back to browser printing.
2. Your own ERPNext Print Format. Set a Print Format on the POS Profile and it takes over, giving you full control over layout, bilingual receipts, QR blocks, anything a Print Format can do.
3. The built-in receipt designer. In Settings → Receipt, choose a template (Compact, Standard, Detailed), pick what to show (item code, barcode, serial number, unit price, payment methods, note, tax ID, address, terms), and add a logo, header and footer. A live preview shows your changes as you make them.

A different receipt per outlet

At the top of the designer, Editing receipt for lets you switch between All outlets (default) and a specific POS Profile. Give a branch its own logo, header, footer, template and fields. Outlets with their own receipt are marked with a dot, and Reset to default puts one back. At the till, each outlet prints its own receipt if it has one, otherwise the shared default.

Put any field on the receipt, including a ZATCA QR

Under Custom fields you can add any field from the POS Profile or from the sale itself onto the receipt:

So a ZATCA QR stored as an image field on the invoice prints as the actual QR, and a CR number, a branch licence, or any country-specific line prints as text. Fields are global by default, with per-outlet extras, and everything shows in the live preview as you build it.

Working offline

LumenPOS is built to keep selling through a network outage.

• Products, prices and promotions are cached on the device the first time you open the POS online, and refreshed in the background.
• If the connection drops, the till keeps working. Sales are queued locally and upload automatically when you're back online. Queued writes carry a safety key so a lost confirmation can never post a sale twice.
• The offline sales log (open from the Offline / Syncing pill in the top bar, or Settings → Status) shows every offline sale and its status: Pending (queued), Uploaded (posted, with the real invoice number), or Needs attention (the server rejected it, with the reason). Nothing is removed until the server confirms it, and one rejected sale never blocks the good ones behind it.
• Queued sales must upload before you can close the register. They belong to this shift's drawer.

A few things need a connection and can't be queued: serialised items, delivery-app sales, gift-card and loyalty redemption, and store-credit and cashback payments.

Named customers with a customer-group price book keep their shelf price offline. The correct price is re-resolved when the sale syncs.

Serial numbers

For serialised products, LumenPOS enforces scanning so the right unit is sold:

• A serialised item won't enter the cart until you scan or type a serial number.
• The serial must exist, be Active, and belong to this register's warehouse.
• Quantity is locked to the number of serials scanned. There's no automatic FIFO pick.
• Serialised items can't be sold offline, because the serial has to be validated live.

Multi-company and invoice modes

Multi-company. If your site runs several companies, LumenPOS scopes accounts per company, so a sale never posts to another company's ledger. Set per-company accounts under Settings → Company Accounts.

Invoice mode. Choose per POS Profile how sales post:

• POS Invoice (default). Sales post as POS Invoices and consolidate the ERPNext way at register close.
• Sales Invoice. Sales post directly as Sales Invoices. Useful when your accounting prefers Sales Invoices, and you can still run opening and closing entries for cash control.

Both modes move stock, post to the ledger, and appear in reports exactly as ERPNext expects. The promotions applied to each sale are stored on the invoice for auditing.

Permissions and the audit log

Under Settings → Permissions, decide which roles can:

• edit a price or apply a discount at the till,
• process a return, and
• approve a return beyond the return window.

When a cashier needs an over-limit discount or a late return, they send an approval request. The approver sees what is being approved, the cart lines being discounted or the items being returned, instead of a bare percentage. Anything still unconfirmed is voided when the shift closes, so an approval can never be spent on the next shift's drawer.

Sensitive actions such as over-limit discounts, returns, register open and close, settings changes, receipt emails, and till unlocks are written to a LumenPOS Audit Log you can review in the desk.

There's also an optional till lock, a lock screen that engages manually or after a period of inactivity. Each cashier sets their own PIN, so an unlock is always attributable to a person. See The register.

Insights

The Insights page gives managers a full sales dashboard without leaving the till. At the top sit net sales, the number of invoices, the average basket and returns. Below them are sales by day, sales by outlet, the payment mix, top items, sales by cashier and the busiest hours of the week. Filter everything by date range, outlet, customer, payment method or item, and open the same dashboard full screen in Lumen Reports with one click.

LumenPOS does not draw the charts itself. The dashboard comes from the separate Lumen Reports app and is embedded inside the POS, in the till's own language and theme. If Lumen Reports is not installed, the page explains how to get it. Once it is installed, one tap builds the dashboard. The page is for managers only and can be switched off in Settings.

Requirements: Frappe v14, v15 or v16 with Lumen Reports installed (1.2.2 or newer on v14, 1.1.0 or newer on v15 and v16). On v13 the page says the dashboard needs a newer Frappe instead of showing a broken screen. A manager who has no Lumen Reports role yet is told which role an administrator grants. The two apps are independent, so each still works on its own.

Keeping a big shop fast

On a large site with hundreds of thousands of sales, LumenPOS relies on database indexes to keep selling, searching and shift reports quick. Settings → Status → Performance indexes lists each one as Built, Missing or Not on this site, with a Rebuild missing indexes button that runs in the background.

This is visible on purpose. Building an index on a huge, busy table can be refused by the database, and previously that failed silently. If a site ever feels slow, check here first.

The same page shows the offline catalogue and customer cache sizes, the connection state, and a link to the offline sales log.

Language

LumenPOS is bilingual, English and Arabic, with full right-to-left layout. Switch language from the top bar. New installs follow your ERPNext desk theme (light or dark) until you override it.

Troubleshooting and FAQ

A sale showed an error and didn't complete. Did I lose it?

No. If a sale can't post, the whole thing is rolled back, so there's no half-made invoice to clean up. Any invoice number you saw in the error is just a skipped number, which is normal. Your cart and payments stay on screen. Fix the cause and press Complete Sale again. If the fix needs an app update, park the sale and complete it afterwards.

How do I correct a sale that already posted?

Submitted invoices can't be edited, which is an accounting rule. Refund or return the sale to reverse it, then ring the correct one, or in the desk cancel and amend the invoice. During a shift, the refund route keeps your drawer count consistent.

The receipt isn't using my custom layout.

Set your Print Format on the POS Profile. When one is set, it takes over printing and the built-in designer only styles the on-screen receipt. A configured thermal printer uses its own fixed layout.

Selling a gift card or paying with one fails on a multi-company site.

Make sure the company has its own warehouse and gift-card or liability accounts. LumenPOS auto-creates sensible defaults, but a valid warehouse for the company must exist. Keep the app up to date, since multi-company handling improves with releases.

Nothing loads, or search is empty.

Open the POS online at least once so the catalogue can cache. Then use Settings → Status → Refresh offline catalog to rebuild the cache.

Do I need to turn off ERPNext Pricing Rules to use promotions?

No. LumenPOS ignores ERPNext Pricing Rules automatically on every POS sale, so its price books, promotions and bundles always take precedence at the till. There's nothing to switch on or off. Your Pricing Rules keep working on non-POS documents.

Where do I change the price list, taxes or payment methods?

On the POS Profile in ERPNext, which is the source of truth. The in-POS Settings page covers promotions, price books, receipts, permissions and the like.

Support

Running into something not covered here? Get in touch:

• Email: hello@lumen-solutions.co
• Website: Book a call

Please include your ERPNext version and, if you hit an error, the message shown at the till. It makes fixing things much faster.

Licence and trademarks

LumenPOS is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0-only). You may use, study and modify it. If you distribute it, or run a modified version as a network service, you must offer your complete source code to the people who receive or use it, under the same licence, and keep every copyright notice.

For a commercial licence without the AGPL obligations, contact hello@lumen-solutions.co.

"LumenPOS" and the LumenPOS logo are trademarks of Lumen Solutions. The code licence does not grant permission to use them, so forks and modified versions must carry a different name and logo.

Versions up to and including 0.38.0 were published under MIT, and versions 0.39.0 to 0.42.1 under GPL-3.0-or-later. Those grants are not revoked. A copy obtained under either keeps those terms for its recipient.