Appearance
Receipt Printing Setup
For automatic, dialog-free printing use QZ Tray (desktop) or Web Bluetooth (tablet). The browser dialog method works on any device but requires a manual confirmation each time.
Which method should I use?
| Method | Best for | What you need |
|---|---|---|
| QZ Tray | Windows, Mac, or Linux desktops with USB or network printers | QZ Tray app installed on the computer |
| Web Bluetooth | Android tablets or Chromebooks with a Bluetooth thermal printer | Chrome or any Chromium-based browser (Edge, Brave, Opera) and a Bluetooth printer |
| USB Printer | Desktops where you prefer not to install QZ Tray (experimental) | Chrome or Edge with a USB receipt printer |
| Browser dialog | Any device, any printer | Nothing extra |
| Disabled | Paperless environments | Nothing |
Setting Up QZ Tray (Recommended for desktop)
QZ Tray is a free app that runs quietly in the background and lets ClarityPOS print receipts without any pop-up dialogs.
Step 1: Install QZ Tray
- Download QZ Tray from qz.io/download and install it on the computer.
- Launch QZ Tray. It runs quietly in the background. You will see a small icon in the system tray (bottom-right corner on Windows, menu bar on Mac). You do not need to open a window.
Step 2: Approve ClarityPOS on this computer (one time)
The first time ClarityPOS prints, QZ Tray shows a small security window asking for permission to use your printers. This is normal. The quick setup below tells QZ Tray to trust ClarityPOS, so you can tick Remember this decision and never see that window again on this computer.
Why do I need to do this?
QZ Tray protects your printers by asking before any website can use them. Approving ClarityPOS once tells QZ Tray that this is a website you trust.
- Go to Settings and select Receipt Printing.
- In the Set up silent printing box, click the download button for your operating system, then unzip the downloaded file.
- Run the setup file for your system:
- Windows: double-click Setup-Windows.bat, then choose Yes when asked for permission. If a blue notice appears, choose More info, then Run anyway.
- Mac: open the Terminal app, type
bash(with a space at the end), drag setup-macos.command into the Terminal window, and press Return. - Linux: open a terminal in the unzipped folder and run
bash setup-linux.sh.
- Reload ClarityPOS. The security window now reads "Verified by LucidaraSoft". Tick Remember this decision, then click Allow.
You only do this once per computer
After you approve it, receipts print silently on this computer with no more pop-ups. Repeat these steps on each till that prints receipts.
Still asked on every sale?
Fully quit QZ Tray (right-click its icon in the system tray or menu bar and choose Exit or Quit), then open it again and reload ClarityPOS. Choosing Reload from its menu does not refresh the certificate.
Step 3: Connect from ClarityPOS
- Go to Settings and select Receipt Printing.
- Select QZ Tray from the print method options.
- Click Auto-Detect. The status badge turns green ("Connected") when QZ Tray is found.
- Select your printer from the Printer dropdown. This lists all printers registered on the computer, including USB and network printers.
- Click Test Print to confirm everything is working.
QZ Tray on a different computer or port
If QZ Tray is running on another computer on your network, or on a non-default port, expand Advanced and enter the host address and port before clicking Auto-Detect.
Network printer without a driver (raw IP printing)
Some network thermal printers support direct IP printing on port 9100 without a driver. To use this, first register the printer as a generic TCP/IP port printer in your operating system:
- Windows: Go to Printers and scanners, click Add a printer or scanner, then The printer that I want isn't listed. Choose Add a printer using a TCP/IP address or hostname and enter the printer's IP address and port
9100. - Mac: Go to System Settings, Printers and Scanners, click the plus button, select IP, and enter the printer's IP address and port
9100.
Once set up at the OS level, the printer appears automatically in the Printer dropdown in ClarityPOS. Select it and click Test Print to verify.
Setting Up Web Bluetooth
Browser requirement
Web Bluetooth requires Chrome or a Chromium-based browser (Edge, Brave, Opera) on a device with Bluetooth. It does not work in Firefox, Safari, or any browser on iOS (iPhone or iPad).
- Go to Settings and select Receipt Printing.
- Select Web Bluetooth from the print method options.
- Click Pair Printer. Your browser shows a list of nearby Bluetooth printers.
- Select your printer from the list and click Pair. The panel shows the paired printer name once connected.
- Click Test Print to confirm.
After the first pairing, ClarityPOS reconnects to the printer automatically when the page loads. No pairing dialog is needed (requires Chrome/Chromium version 87 or later).
If automatic reconnection fails, click Change Printer to pair again.
Non-standard Bluetooth printers
Most common thermal printers (Munbyn, ITPP, RPP02) work with the default settings. If your printer does not connect, expand Advanced in the Bluetooth panel and enter the BLE Service UUID and Characteristic UUID from your printer's manual or the manufacturer's website.
Bluetooth Printing on iOS (iPhone or iPad)
Web Bluetooth is not available on iOS. Apple requires all iOS browsers (including Chrome and Edge) to use the WebKit engine, which does not support Web Bluetooth.
The recommended approach for iOS devices is QZ Tray via a shared network computer:
- Install QZ Tray on a Windows, Mac, or Linux computer on the same network as the iOS device, with your printer connected to it.
- On the iOS device, go to Settings, select Receipt Printing, choose QZ Tray, then expand Advanced.
- Check that Secure connection (wss://) is turned on (it is on by default). The port should show 8181.
- Enter the host computer's local IP address (e.g.
192.168.1.10) in the Host field. - Click Auto-Detect. ClarityPOS connects to QZ Tray on the remote computer and prints through it.
The Browser dialog method also works on iOS using Safari's native print sheet, but requires a manual tap after each sale and needs an AirPrint-compatible printer.
USB Printer (experimental)
The USB Printer option lets Chrome and Edge print directly to a USB receipt printer without installing QZ Tray. It is experimental and works on Windows, macOS, and Linux.
Browser requirement
USB Printer requires Chrome or Edge. It does not work in Firefox, Safari, or any iOS browser.
- Connect your USB receipt printer to the computer.
- Go to Settings and select Receipt Printing.
- Select USB Printer from the print method options.
- Click Pair USB Printer. Your browser shows a list of connected USB devices.
- Select your printer and click Connect.
- Click Test Print to confirm.
If your printer is not listed, check that it is powered on and the USB cable is seated properly. Some printers require a driver before they appear in the browser picker.
Printing at the POS
Once a print method is configured, receipts print automatically the moment a sale is completed. No extra button presses are needed.
| Method | What happens after a sale |
|---|---|
| QZ Tray | Receipt prints silently with no dialogs |
| Web Bluetooth | Receipt prints silently with no dialogs |
| Browser dialog | The browser print dialog opens automatically |
| Disabled / not configured | A Print Receipt button appears on the sale confirmation screen |
If printing fails for any reason, an error message appears and a Print Receipt button is shown so the cashier can try again.
Reprinting from Sales History
On the Sales page, every completed sale has a Reprint button. It uses the same print method configured in Settings, with the same automatic behaviour and the same fallback if printing fails.
Printer Status Indicator
The cart panel header shows a small coloured dot so you can see the printer status at a glance:
| Dot | Meaning |
|---|---|
| ● Green | Printer is connected and ready |
| ● Amber | Connecting or reconnecting |
| ● Red | Connection error |
| No dot | No print method is configured |
Where Print Settings Are Stored
Print settings are stored locally in your browser on each device. Every workstation keeps its own printer configuration independently, so a desktop computer can use QZ Tray while a tablet at the counter uses Bluetooth.
WARNING
Clearing your browser data or switching to a different browser will reset the print settings. If that happens, go to Settings → Receipt Printing and configure it again.
FAQ
Q: Receipts are not printing after a sale. What should I check?
A: Work through these steps:
- Look at the printer status dot in the cart header. A red or amber dot means there is a connection problem.
- Go to Settings, open Receipt Printing, and click Auto-Detect (QZ Tray) or check the paired device name (Bluetooth).
- Click Test Print to find out whether the issue is with the connection or with the printer itself (paper, power, cable).
- If using QZ Tray, check that the QZ Tray icon is still visible in the system tray. It may have been closed or restarted.
Q: QZ Tray shows "Not installed" even though it is running.
A: QZ Tray must be open before ClarityPOS loads. If you started QZ Tray after opening the app, click Auto-Detect in Settings to retry the connection without reloading the page. If Auto-Detect still fails, check that QZ Tray is not blocked by your firewall on port 8181 (or the custom port you set in Advanced).
Q: My network printer does not appear in the Printer dropdown.
A: The printer needs its driver installed on the computer. Install the manufacturer's driver (for example, the Epson Advanced Printer Driver or Star Micronics driver) and the printer will appear in the dropdown automatically. If you prefer not to install a driver, use the raw IP option under Advanced instead and enter the printer's IP address and port 9100.
Q: The "Pair Printer" button for Bluetooth does nothing or is greyed out.
A: Web Bluetooth requires Chrome (version 56 or later) running on a computer or Android device with Bluetooth hardware. It does not work in Firefox, Safari, or any iOS browser. The settings panel will show an explanation if your browser does not support it.
Q: I paired a Bluetooth printer but it is not reconnecting after I reload the page.
A: Automatic reconnection requires Chrome version 87 or later. If your Chrome is older, click Change Printer and pair again after each page reload. Updating Chrome to the latest version fixes this permanently.
Q: Can a cashier change the print method?
A: Yes. All roles, including Cashiers and Managers, can configure the print method and printer in Settings. Print settings are stored on each device, so every workstation manages its own printer independently.
Q: Will print settings sync between computers?
A: No, and this is by design. Print settings are stored locally on each device because different workstations use different printers. An Admin must set up printing separately on each device.
Q: Our receipts need a logo. Is that supported?
A: Not in the current version. Receipt headers support text only, including store name, address, phone, and email. Logo printing may be added in a future update.
Q: Can I use a Star Micronics or non-Epson printer?
A: Yes. Any printer that supports the ESC/POS command set will work, and most modern thermal receipt printers from any brand do. For Bluetooth printers, the default connection settings cover most common models. If your printer does not connect, check the BLE Service UUID and Characteristic UUID in your printer's manual and enter them under Advanced in the Bluetooth panel.
Q: Does QZ Tray require a paid licence?
A: No. QZ Tray is free to use. There is no subscription or per-use fee for running it on your own hardware.