Lumen Solutions Documentation · LumenPOS

LumenPOS Guide

Everything from installing the app to running a busy shift, for shop owners, managers, and the ERPNext admin setting it up.

Frappe / ERPNext v13 to v16 28 sections
In a hurry?
Install the app → Open a POS Profile & add your cashier → Go to https://your-site/pos → Enter opening float → Start selling

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, cashback, gift cards, store credit, loyalty points, returns and exchanges, holds and deposits, sales on account, cash-drawer reconciliation with a blind count, sales reports and a cashier watch list, barcode and price labels, stock take from the till or the Lumen Stock phone app, thirteen languages, sales in other currencies, 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.

Developers: if you change anything under frontend/src, rebuild and commit the assets:

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.
  • Items often bought together. After an item goes in the cart, the till suggests up to three items customers of this outlet often buy with it, worked out from the outlet's own sales. One tap adds it. Items already in the cart, serialised items and items out of stock are left out, and the suggestions work offline too. Insights → Bought together shows what they brought in.
  • Salesperson. Type a name or the salesperson number and pick. The person stays for the next sales, is recorded on the invoice's Sales Team at 100% with the commission ERPNext works out at their rate, and prints on the receipt. Salespeople are ERPNext's Sales Persons. Under Settings → General → Features, naming one is optional (the default), required before Pay, or off.

The Salespeople tab of Insights adds up each person's sales, returns, net and commission over a period. A return counts against the salesperson of the sale it takes back. Managers see it, and so does anyone named for See sales by salesperson in Permissions. Only they see the commission on the shift report.

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.

LumenPOS pricing vs ERPNext Pricing Rules. LumenPOS owns pricing at the point of sale. Its price books, promotions and bundles are always the source of truth, and it automatically ignores ERPNext Pricing Rules on every POS sale, so the price the till shows always matches the posted invoice, and there's nothing to enable or disable. (You may see an Ignore Pricing Rule option in ERPNext. LumenPOS already applies it for you at the POS.) Your existing Pricing Rules keep working on non-POS documents such as Sales Orders and regular Sales Invoices.

Type What it does Key fields
Simple Discount A percentage or fixed amount off matching products Discount type, value
Buy X Get Y Multi-buy offers such as buy 2 get 1 free. The cheapest qualifying unit is the one discounted Buy qty, get qty, reward, max applications
Spend & Save A basket-level discount once the cart passes a threshold Minimum spend, basket discount
Bundle Price Sells listed products together for one fixed price. The bundle's items appear as separate lines on the invoice Products, quantities, bundle price

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.
  • Amount in another currency. Where the shop takes other currencies, type what the customer hands over in that money, and the till converts it at the shift's rate. The receipt shows both, and the sales reports show what each method took in its own money. See Selling in other currencies.

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.

Selling in other currencies

For a shop whose customers pay in more than one currency, such as a tourist paying in dollars at a riyal till, or a customer billed in dollars. Switch it on under Settings → General → Other currencies (Sell in other currencies), add the currencies, save, then set each rate.

  • What saving sets up. For each currency, in every company that has an outlet, LumenPOS creates ordinary ERPNext records: a receivable account, a cash account, a payment method such as Cash USD added to every outlet, and a walk-in customer billed in that currency.
  • Which currency a sale is in. The customer's Billing Currency in ERPNext. Pick a customer billed in dollars and the whole sale is in dollars. A walk-in can be switched with the currency picker beside the channel on the cart, or with Sell in on the payment screen, and a named customer always buys in their own currency. The cart can show each total in the other currencies too.
  • Prices. One price list in the outlet's currency is all a shop needs. Price books, bundles, offers and discounts stay in that currency and are converted at the shift's rate, so nothing is priced twice. To fix prices in another currency instead, make a selling price list in that currency and set it as the Default Price List of that currency's walk-in customer, of a customer, or of their customer group. Every item that list prices sells at its own figure, and an item it does not list keeps the outlet's price, converted at the shift's rate.
  • Exchange rates. Rates are kept in ERPNext (Currency Exchange, selling) and set in the same Settings card. A shift fixes the rate of every currency as it opens and keeps it until it closes, so a sale and its refund always match, and a new rate applies from the next shift.
  • Automatic rates (optional). Tick Update exchange rates automatically and choose, for each currency, a Fixed rate (the one you set) or an Automatic rate. Once a day, a quarter past midnight, LumenPOS reads the published rates from ExchangeRate-API (free) and saves today's rate of every Automatic currency in ERPNext, exactly as if someone had typed it. Update now does it at once. An Automatic currency can carry a margin, so the till values it that much below the published rate. A rate typed for today always wins for that day, and if the rates service cannot be reached, the last rate stays in force.
  • Paying. Each payment is typed in the money actually handed over. The payment screen asks Amount in dollars or riyals, converts at the shift's rate and shows what is left in both. Local cash and cards are always offered, and the dollar cash drawer only on a sale in dollars. Change comes back in local money from the main drawer, unless you set a currency to give change in its own money.
  • The shift and the receipt. Each drawer in another currency keeps its own opening float, cash in and out, expected amount and count, in its own money. Takings, discounts and variance alerts are in the company currency, and the X-report lists the rates. The receipt shows the sale in its currency, its local value and the rate, with each payment in the money it was made in. Refunds go back in the sale's currency at its original rate.
  • Reporting. The Payments table of the sales summary in Insights shows, under each method's amount in your company currency, what it took in other currencies in their own money, with a line below the table totalling each currency. The CSV download carries the same figures.

What stays in the outlet's currency. Gift cards, store credit, cashback, loyalty redemption, holds and exchanges keep one currency in their ledgers, so they are refused for a sale in another currency with a plain message. Sales on account are for the company's currency only.

Without a connection. A sale in another currency can be made offline, to that currency's walk-in customer. The till prices it at the rate the shift fixed as it opened, and the server posts it only at that rate. A named customer billed in another currency needs a connection.

With the switch off, a customer billed in another currency is refused at the till, with the reason, instead of being posted wrong.

Holds, deposits and sales on account

Holds and deposits (layaway)

For a customer who wants the goods kept while they pay for them over time. Ring the items up as usual, pick the customer, then press Hold instead of Pay. It is switched off until you want it, under Settings → General → Holds and deposits. A shop that never puts goods aside sees nothing of it.

  • The Hold window shows what is being held and asks for the deposit and how it was paid, plus a date to hold until and a note. The shop can insist on a minimum first payment.
  • The goods are reserved. LumenPOS raises a Sales Order, so ERPNext shows the quantity as committed and another till cannot sell the last one. A shop that does not want that can switch it off.
  • The Holds screen lists what is on hold, for whom, paid and still to pay, and flags anything past its date. From there you take another instalment, hand the goods over, or cancel.
  • Hand over sells the goods at the price agreed on the day of the hold, takes the balance, releases the reservation and closes the hold.
  • Cancel refunds every instalment through the ordinary return, so the refund rules the shop set apply, and the goods go back.

Anyone can hold goods unless the shop names a role or a person for Hold goods for a customer in Permissions. A hold reserves stock and posts documents, so it needs a connection.

Where the money sits

A deposit is not a sale. Each instalment posts a real POS sale of one line, a Customer Deposit, whose income account is a liability. The drawer and the Z-report see the money the moment it is taken, but nothing is counted as revenue while the goods are still in the shop. At hand-over, what was already paid comes off the bill and only the balance is collected. The figure a hold quotes is what the customer will pay in the end, tax and all, worked out on the day the hold is made and frozen there.

By default the deposit carries no tax and the goods are taxed in full when they are handed over. Turn on Deposits are taxable when taken where an advance is taxable on receipt. The deposit is then invoiced with the tax inside the amount handed over, and at hand-over that advance is deducted from the taxable amount, so the same money is never taxed twice.

Sales on account

A customer takes the goods now and pays later, all of it or the rest after paying part. The sale is a POS invoice like any other. Turn it on under Settings → General → Sales on account. It is off by default, and while it is off the till shows nothing about it.

  • Who can buy on account. Only customers allowed on their card (a manager ticks Allowed to buy on account on the customer), or any named customer. Never the walk-in customer.
  • The limit. ERPNext's own credit limit applies first (the customer's, then their group's, then the company's). A Default credit limit in Settings covers a customer with none, and 0 means no limit. The limit is checked at the sale, not at the close: the till refuses a sale that would take the customer past it and says what is left. Open holds are not counted as owed, but they do count against the limit.
  • At the till. Choose the customer, press Pay, take what the customer pays now, then Put … on account for the rest. The card shows what the customer already owes and what their limit leaves. The receipt shows what is still owed on the sale and in all, with a line for the customer to sign.
  • In ERPNext. LumenPOS creates a Credit Sale payment method and a clearing account in each company that has an outlet. The part on account is paid by that method, and LumenPOS books the debt on the customer with its own Journal Entry, so it shows on the customer's account and in Accounts Receivable at once.
  • Taking a payment. A customer's page has an On account card with what they owe, their limit and each sale still owing, oldest first. Take a payment settles the oldest sales first, or the sales you tick, in cash or by card, and counts the money into this till's drawer, so the register must be open. It never takes more than is owed.
  • Returns. What comes back goes off what the customer still owes on that sale first, and only the rest goes back as money. A sale still owing is not exchanged: take it back, then sell the new goods.
  • Not allowed. A walk-in customer, a customer who is not allowed on their card, a sale in a currency other than the company's, a sale made without a connection, and a gift card or a hold on account.

Who may sell on account, take customer payments and set a customer's credit is set in Permissions. Until someone is named there, only managers can.

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. See Cash out under control below.
  • 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, and LumenPOS compares counted vs expected per payment method and produces a Z-report.
  • The top bar shows how long the shift has been open, by the site's own clock.

Blind count

With Settings → General → Register and shifts → Blind count at the close on, a cashier counts each drawer and each way of paying without seeing what the system expects. The Register page shows them no expected takings, sales or difference, the X-report is hidden, and the server gives them none of those figures. They type what they counted and press Send the count. From then on the shift takes no more sales, refunds or cash movements, and waits for a manager.

The manager opens the shift, sees the cashier's count beside the expected figures, and closes it, or sends it back to be counted again. What the cashier counted is kept with the shift even when the manager closes on another figure. Managers always see the figures, and anyone else who should is named under the See the expected takings permission.

A reason for a short or over

When the counted drawer differs from what it should hold, the close panel asks why. The person closing writes the reason in their own words, or taps one of the shop's quick reasons, and can say what was done about it. Both stay with the shift and go in the variance email. Under Settings → General → Register and shifts the setting is Optional (the default), Required (the register does not close without one, checked on the server too) or Off. With Required you can also set a difference below which nobody is asked.

Cash out under control

Putting money in and taking it out are two separate permissions. Settings → General → Approvals and access → Cash out can ask a reason for every cash out (on by default) and a manager's approval: off (the default), above an amount, or always. The cashier then types a supervisor's passcode, or sends a request that a manager approves from the Approvals tray. An approval covers that shift, that drawer and that amount, once. Who approved shows under the movement on the Register page and in the audit log.

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 → General → Register and shifts → A shift belongs to you choose:

  • The cashier (the default). 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.
  • The outlet. One shift per register, and any assigned cashier can sell on it. A site that already had shifts keeps the way it worked until you change it.

ERPNext 16 holds one open shift per register at a time. Where each cashier counts their own drawer, give each cashier their own register (POS Profile) on the same warehouse, and they stay one outlet. Where one shared drawer is enough, let the shift belong to the outlet.

One open shift per person (optional, under Settings → General → Register and shifts, off by default) stops someone opening a new shift while they still hold one at another outlet. Nobody is locked out by it: a shift whose close has started, or that nobody can reach any more, never blocks anyone, and a manager can close any cashier's open shift from the Register page, under Other open shifts here.

Outlets and their registers

A POS Profile is a register: one till, with its own shift and drawer. An outlet is the shop its registers stand in. Registers that sell from the same warehouse are one outlet, with nothing to set up. To split a warehouse between outlets, or to keep one outlet over several warehouses, fill Outlet on each POS Profile. Registers with the same Outlet name are one outlet, whatever their warehouse, and outlets never cross companies.

The till reads Outlet · Register when its outlet has more than one register. Every report in Insights picks This register, This outlet or every outlet of the company, and the Outlets tab shows one card per outlet with each register's sales, shifts, and overs and shorts.

Shifts past midnight and locked periods

Past midnight (ERPNext 16). ERPNext 16 takes sales only on a shift opened the same day. With Keep a shift open past midnight on (Settings → General → Register and shifts, on by default and shown on ERPNext 16 only), the first sale after midnight closes the day in ERPNext and opens the next one by itself, the way ERPNext does it. The shift carries on, and the cashier counts the drawer once, at the end, against the whole shift. With the switch off, a shift from an earlier day refuses every sale until it is closed and a new one is opened. Before ERPNext 16 a shift simply runs past midnight.

A locked accounting period. An ERPNext Accounting Period made ahead of time lets the till sell all day and then stops the close. LumenPOS warns before the shift opens, and a close it stopped names the period and what to do.

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.

Exchange in one step

A customer swapping one thing for another is not two errands. In History, open the sale and choose Exchange instead of Refund.

  • Pick what is coming back, exactly as for a refund. Return restrictions, the return window and its approval request, serial numbers and sets that must come back together all still apply.
  • Press Pick the new items. The till returns to Sell with a banner showing which sale is being exchanged and what the returned goods are worth. Ring up what the customer takes instead, the usual way.
  • Pay shows the new items, the credit for what came back, and one line for what is actually owed. If the new items cost more, you collect the difference with any tender. If they cost less, you give the difference back by the same rules as a normal refund. If they are equal, nothing moves in the drawer.

Both documents post together in one request, a credit note for the goods returned and a POS sale for the replacement. If anything fails, neither exists. The matched part goes through a clearing tender called Exchange, so the drawer, the card totals and the Z-report only see the difference. The replacement sale is tagged EXCHANGE in History. An exchange needs return permission, and a role or person can be named for Exchange goods in Permissions. It needs a connection.

A supervisor approves the refund

Under Settings → General → Approvals and access → Refund approval choose Off (the default), Above an amount or Always. When the cashier presses Refund, the server values the refund exactly as it will post it, tax included, and if an approval is needed the till asks for it. A supervisor types their passcode, or the cashier sends a request with the amount, which the approver role or a manager approves from the Approvals tray. The approval covers that amount and no more, and is used once. Who approved is written on the credit note and in the audit log.

Only money handed back counts, so an exchange needs the approval only when it gives money back, and only for that difference. Managers need nobody's approval. Without a connection such a refund waits for one, because the server checks the passcode.

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.

Setup tip: to switch loyalty on, create a Loyalty Program in ERPNext, set it to auto opt-in and assign it to customers. On ERPNext v15 and v16, also tick Allow Partial Payment on the POS Profile, otherwise ERPNext refuses any sale paid partly with points: it counts only the cash and card against the total, even though the points settle the rest. LumenPOS checks every sale adds up before it posts, so nothing is lost by ticking it. To use store credit, just take it as payment. The account and payment method are created on first use.

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:

ChooseMeaning
SourcePOS Profile (branch details) or Sale invoice
FieldPicked from a dropdown of that record's fields. Your own custom fields appear here too
LabelWhat prints before the value (optional)
Show asText, or Image / QR
WhereHeader or Footer

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.
  • The till opens without a connection (Frappe v14 and later) and survives a reload and a reboot. The app itself is kept on the device by a service worker, so /pos opens with no connection at all and the shift carries on, with the cached catalogue and queued sales. It needs one online visit first, and Settings → Status says Opens without a connection: Ready once it is in place.
  • Install it like an app. From Chrome or Edge on the till, choose Install (or Add to home screen) and LumenPOS gets its own window and icon, with no address bar, and starts straight at /pos.
  • Returns without a connection. Sales History lists this device's own sales of the open shift, those already sent and those still waiting, and any of them can be taken back there. Pick the items and the reason, and refund at the exact figure ERPNext will post, in cash or the way the customer paid, never onto store credit, a gift card or cashback. The server checks everything again when the return is sent, and it waits in the queue behind the sale it takes back. It is on by default and can be switched off in Settings. Not available offline: serial numbers, a sale paid with loyalty points, products the shop takes back only with an approval, and a sale with a service charge.
  • Uploads in the background. Queued sales go up as soon as the connection is back, even with the till closed, where the browser allows it.

On Frappe v13, keep the tab open during an outage. The part of the app that opens the till without a connection is not available on v13, so refreshing or navigating away while fully offline can't reload it there. Any queued sales are still safe.

A few things need a connection and can't be queued: serialised items, delivery-app sales, gift-card and loyalty redemption, store-credit and cashback payments, sales on account, exchanges, holds, and opening or closing a shift. Open the shift while you have a connection, and the till can sell through an outage on its own.

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.

Barcode and price labels

The Labels screen prints shelf and product labels on a label printer roll or on an A4 sheet of labels.

  • Pick the items by scanning or searching, take every item a Purchase Receipt, Stock Entry or stock-updating Purchase Invoice brought in (one label per unit received), or every item whose price changed since a date.
  • The price on the label is what a walk-in customer pays at this outlet, price books included and tax included, worked out the way ERPNext works it out (item tax templates too). Where you sell in other currencies, the label can show those prices as well.
  • The barcode is the item's own EAN-13 or UPC-A. An item without one prints its item code as a Code 128 barcode, which the till scans too.
  • Sizes: rolls of 50 x 25, 40 x 30, 58 x 40 and 38 x 25 mm, A4 sheets of 3 x 8 or 4 x 10, or a custom size. Choose what prints: shop name, item name, price, other currencies, barcode, item code.
  • A switch in Settings turns the screen off, and the Print labels permission limits who may print.

Stock take with the Lumen Stock app

LumenPOS works with Lumen Stock, a phone app for warehouse and shop-floor stock work. Staff count stock, receive and transfer goods, and record purchase receipts from an Android phone or a handheld scanner, and every document lands in ERPNext as a normal Stock Reconciliation, Stock Entry or Purchase Receipt, saved as the person who made it, so their ERPNext permissions apply.

  • Count with several phones at once. Open a shared count for a warehouse, each phone sends what it counts, and a supervisor merges everything into one stock count. The same item counted on two phones is added up, serial numbers are combined, and only the differences go into the count. A full count sets anything nobody counted to zero.
  • Counts that match the shelf. A sale at the till moves stock only when its shift is closed. LumenPOS compares a count with what is really on the shelf, and a count is not saved, merged or submitted from the app while sales of an open shift still hold its items, so no difference is lost and closing the shift afterwards never takes the same goods off twice. Phones keep counting meanwhile.
  • Moved after counting. Before a count is submitted, the items that were sold, moved or received after they were counted are listed with the documents that moved them.
  • In the desk each shared count shows every phone, every item, the total, what is on the shelf and the difference, with an Excel export.
  • Settings switch the app off or any part of it (counts, stock entries, purchase receipts, approving from the app, shared counts, blind counting, linking a new barcode to an item, the Excel export), and the Use the stock app permission limits who may use it.

Count from the till

A shop that already has a barcode scanner at the counter can count without the app: the till has its own Stock count screen. Pick the warehouse and scan, one scan per unit. Save makes a Stock Reconciliation draft of only the items that differ from the shelf, alone or as one more device of a shared count. It follows the same rule as the app: no count is saved while sales of an open shift still hold its items. It needs the Use the stock app permission and ERPNext's own right to make a stock count.

Getting the app, and which device

Settings → General → Features → Lumen Stock app has the download links, one for Android phones and one for older handheld scanners. An Android handheld with a built-in scanner counts much faster than a phone camera. The app was tested on the Honeywell ScanPal EDA51, other Honeywell EDA and CT models work with no setup, and Zebra (TC21, TC26), Urovo (DT40), Chainway (C61) and other brands work once their scanner is set to keyboard mode with Enter after each code.

Lumen Stock also works on ERPNext sites without LumenPOS. More on the app: Lumen Stock.

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

ERPNext roles decide what a person can reach. Under Settings → General → Approvals and access → Permissions a table decides what they may do at the till, and each row can name a role or one person. So “the shift leads, plus Fatima” is two rows, not a role invented for one person. You can control:

  • edit a price or apply a discount at the till,
  • make returns, return past the window without an approval request, and exchange goods,
  • cash in and cash out, as two separate actions,
  • reprint a receipt,
  • open the register and close the register,
  • see the expected takings (for the blind count),
  • hold goods for a customer,
  • sell on account, take customer payments and set a customer's credit,
  • print labels and use the stock app,
  • see the sales reports, see profit, see cashier performance, see sales by salesperson and see the cashier watch list, and
  • see the system check.

Rules for the same action add up: any row that matches lets the person through. An action with no row is open to everyone, so nothing locks up the day you update. The sensitive ones stay shut until somebody is named: returning past the window (everyone else sends an approval request), seeing the expected takings, the five reports above, seeing the system check, and the three sales-on-account actions. System and LumenPOS Managers always pass. The till hides what a person may not do, and the server checks every one of these actions again, so a stale browser tab or a direct API call cannot get round it.

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 gathers the shop's reports inside the till. Each report covers a period (today, yesterday, the last 7 days, this month or any dates) and one register, one outlet or every outlet of the company, in the company's currency, with Download CSV.

  • Sales summary: sales, average sale, net sales, tax, returns and discounts, the payments by method (with what each took in other currencies in their own money), the sales day by day or hour by hour, and every shift with its count against what was expected and the over and short.
  • Products: what sold by item, item group, brand, product with variants and attribute (size, colour), and for whoever may see the profit, the cost, gross profit and margin.
  • Profit: net sales, cost of goods, gross profit and margin, by day and item group, costed the way ERPNext's own Gross Profit report costs them.
  • Customers: new and returning customers, the average basket, the top customers and regulars, beside the walk-in sales.
  • Outlets: each outlet side by side with its registers, shifts, stock, items at the reorder level and best sellers.
  • Cashiers: each cashier's sales, returns, discounts, prices typed at the till, shifts and over and short.
  • Salespeople: sales, returns and commission per salesperson, which ERPNext's own reports do not show for POS sales.
  • Cashier watch list: each cashier's returns, own returns the same day, discounts, lines removed before payment, discarded sales, typed prices, reprints, cash out and short closes, each set against the usual figure of the other cashiers. Those well above it are marked Watch or Review, a reason to look, not proof of anything. A daily summary can go by email every morning.
  • Bought together: what the till's suggestions brought in, by cashier and by item.
  • Sales dashboard: with the separate Lumen Reports app installed (Frappe v14 and later), a full charts dashboard in the till's own language and theme.

Managers see every report. Anyone else is named for See sales reports, See profit, See cashier performance, See sales by salesperson or See the cashier watch list, all closed until you name someone. The sales reports, the watch list and the suggestions each have their own switch in Settings.

The sales dashboard

The dashboard comes from the separate Lumen Reports app and is embedded inside the POS. 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. If Lumen Reports is not installed, the page explains how to get it. Once it is installed, one tap builds the dashboard.

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.

Reports without a till

Owners and managers who read the figures but never sell do not need a POS Profile. Give their ERPNext user the LumenPOS Reports role and LumenPOS opens on the Insights reports alone, with the top bar reading Reports only: no register, no shift, no products. They read every outlet of the companies their ERPNext User Permissions allow. With the cashier or manager role as well, the person works the whole till. Settings → General → Insights → Reports for management without a till switches it off for everyone.

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 speaks 13 languages: English, Arabic, Spanish, German, Chinese (Simplified), French, Thai, Indonesian, Vietnamese, Portuguese (Brazil), Persian, Russian and Turkish, with full right-to-left layout for Arabic and Persian. Switch language from the top bar, and the server's own messages answer in the same language. Settings chooses which languages the till offers. New installs follow your ERPNext desk theme (light or dark) until you override it.

Help for staff

Every screen has a ? button at the top that opens help for that screen: what it is for, the everyday tasks in short numbered steps, and a Show me tour on the tasks that have one. A tour lights up the real buttons one at a time and only explains, so nothing is sold or changed while it runs.

Someone new is offered a one-minute tour the first time they open the till, and after each update everyone sees once what is new for them, with a tour where there is one. The help speaks the language each person picks and shows only what that person may use.

At the bottom of the help, anyone at the till can send a suggestion to Lumen Solutions, through the site's own outgoing email, with their name only if they choose to include it.

All of it is switched in Settings → General → Help for staff.

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, bundles or price books?

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:

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

LumenPOS is built by Lumen Solutions and improves regularly. This documentation reflects the current release.

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.