POS AWESOME
#### An open-source Point of Sale for [Erpnext](https://github.com/frappe/erpnext) using [Vue.js](https://github.com/vuejs/vue) and [Vuetify](https://github.com/vuetifyjs/vuetify) (VERSION 15 and 16 Support)
---
NOTE: Application is undergoing major refactoring. please report for any bug or issue it will be solved on high priority. For now it is stable and tested.
Recommended to use stable version for production.
### Quick Start
Follow these steps to install and start using POS Awesome:
1. **Install the app** in your bench:
1. `bench get-app https://github.com/defendicon/POS-Awesome-V15`
2. `bench setup requirements`
3. `bench build --app posawesome`
4. `bench restart`
5. `bench --site your.site.name install-app posawesome`
6. `bench --site your.site.name migrate`
2. **Open the POS Awesome workspace**
Log in to ERPNext, go to the home page, and click **POS Awesome** from the left-hand menu.
3. **Create a POS Profile**
- Navigate to **POS Awesome → POS Profile → New**.
- Fill in the mandatory fields:
- **Name** – any label for this profile.
- **Company** – the company under which transactions will be recorded.
- **Warehouse** – the default warehouse for item stock deduction.
- **Customer** – a default customer (create one if none exists).
- **Applicable for Users** – add the users allowed to use this POS.
- **Payment Methods** – add accepted modes (e.g., Cash, Card).
- Optional operational settings:
- Assign trusted users the **POS Awesome Supervisor** role from **User > Roles** when they need supervisor-only POS controls.
- Enable **Allow Offline Sale Without Stock Verification** if offline invoices should be saved even when local stock data is missing or insufficient. Stock is still validated again on the server when the invoice syncs.
4. **Save the profile**
5. **Start selling**
Return to the **POS Awesome** workspace and launch the POS. Select the newly created profile if prompted and begin creating invoices.
For more details, see the [POS Awesome Wiki](https://github.com/yrestom/POS-Awesome/wiki).
### Docker Deployment
POS Awesome is Docker-ready as a Frappe custom-image app. Use
[`docker/apps.json`](docker/apps.json) for ERPNext/Frappe 16 or
[`docker/apps.version-15.json`](docker/apps.version-15.json) for ERPNext/Frappe
15 with Frappe Docker to build an image that contains ERPNext and POS Awesome,
then install `posawesome` on each site and run migrations. See
[`docs/DOCKER_DEPLOYMENT.md`](docs/DOCKER_DEPLOYMENT.md) for the full build,
install, and verification checklist.
Production M-Pesa installations must also follow the
[`M-Pesa callback security upgrade runbook`](docs/M-PESA_CALLBACK_SECURITY.md)
before enabling callback processing after an upgrade.
---
### Update Instructions
After switching branches or pulling latest changes:
1. cd apps/posawesome
2. git pull
3. yarn install
4. cd ../..
5. bench build --app posawesome
6. bench --site your.site migrate
Go to developer tools in browser, then go to application tab, then go to storage and clear site data.
After clearing site data go to browser settings and delete cache and images data in history also.
---
### Update Notifications (POS)
- POS automatically checks for updates every 24 hours.
- Manual check: **Menu → Check for Updates**.
- Updates are checked **only against the current git branch**.
- The update dialog shows **all commits ahead** (commit message + date).
- Dismissed updates will reappear only when a **new commit** is available.
- It only check for updates on the current branch you are on. It will not update in backend.
---
### Project Structure (Modernized)
Key folders in the modernized POS app:
- `frontend/src/posapp/components/pos/` UI split into small, focused components (invoice, items, payments, closing, etc.)
- `frontend/src/posapp/composables/` business logic and state orchestration (invoice, items, payments, offers, offline)
- `frontend/src/posapp/stores/` Pinia stores for normalized app state
- `posawesome/posawesome/api/` backend APIs split by domain (invoice_processing, item_processing, payment_processing)
---
### TypeScript Migration Status
The POS frontend has been migrated to TypeScript. If you add new modules, prefer `.ts`/`.vue` with `lang="ts"` and keep types in `frontend/src/posapp/types/`.
---
### Returns & Discounts (Important Behavior)
- **Return invoices** use negative quantities and negative totals.
- **Additional Discount (Percentage)** is recalculated automatically based on the current return total.
- **Additional Discount (Amount)** is **prorated** on partial returns.
- Applied as a **negative** discount on returns.
- For **Return without Invoice**, discount logic depends on the POS Profile and may require manual adjustment.
---
### Payments & Write-Offs
- Write-off amount is capped by POS Profile and validated against payment coverage.
- Refunds/returns use negative payment amounts.
- Partial payments and credit sales respect the same write-off limits.
- POS Awesome Payments supports **Receive** and **Pay** workflows from the Payments route.
- **Receive** is used for customer payments and can create new Payment Entries, reconcile unallocated payments, reconcile M-Pesa payments, and allocate payments against outstanding Sales Invoices.
- **Pay** supports customer payouts, supplier/vendor payments, and employee payments. Supplier/vendor payments can be allocated against outstanding Purchase Invoices.
- Reconciliation can be done manually by selecting invoices and unallocated payments, or automatically with **Auto Allocate Payment Amount** / auto reconcile.
- Customer reconciliation supports Sales Invoices, credit notes, unallocated Payment Entries, and M-Pesa entries when enabled.
- Supplier/vendor reconciliation supports Purchase Invoices and supplier unallocated payments.
- Payment creation and reconciliation are controlled from POS Profile with `Use POS Awesome Payments`, `Allow Make New Payments`, `Allow Reconcile Payments`, and `Allow Mpesa Reconcile Payments`.
- Multi-currency payment methods are supported with exchange-rate handling when invoice, party, and bank/cash account currencies differ.
---
### Offline Mode
- Invoices, customers, and payments can be created offline.
- Background sync replays changes when connectivity returns.
- Failed offline submissions are saved as Drafts.
- **Allow Offline Sale Without Stock Verification** on POS Profile lets offline invoice saving continue when local stock cache is missing or below the requested quantity.
- This option only skips local offline stock blocking. Server-side stock validation still runs when the invoice syncs online.
---
### POS Awesome Supervisor
Supervisor access is now controlled by the **POS Awesome Supervisor** role on the **User** doctype. This replaces the old user-level `posa_is_pos_supervisor` custom field and uses the new role name instead of **POS Supervisor**.
Users with this role can access supervisor-only POS functions:
- Open the **Awesome Dashboard** from the POS navigation/menu, when the dashboard is enabled for the POS Profile.
- View dashboard data for the current profile, a specific profile, or all allowed profiles depending on dashboard scope settings.
- Use supervisor invoice-management scope to view/search submitted invoices and drafts across the company, with profile filtering available from the invoice management dialog.
- See supervisor-only item rate details such as last purchase rate and cost/manufacturing cost while selecting items.
- Issue and top up gift cards from the payments/gift-card workflows. Non-supervisors can still check gift-card balances when gift cards are enabled.
To grant access, open the ERPNext **User** record and add **POS Awesome Supervisor** in the user's Roles table.
---
### Gift Cards
Gift cards are available when **Use Gift Cards** is enabled on POS Profile.
- Cashiers can scan or enter gift-card codes and check live balance/status.
- Gift cards can be redeemed from the invoice payment screen.
- POS supervisors can issue new gift cards and top up existing cards from the payment/gift-card workflows.
- Gift-card issue and top-up actions create the required accounting entry against the configured gift-card liability account.
- Supervisor management is controlled by POS Profile gift-card settings and the **POS Awesome Supervisor** role.
---
### Purchase Orders, Receiving, And Purchase Payments
The **Purchase Order** module lets users create purchasing documents directly from POS.
- Create Purchase Orders from the POS item selector.
- Select supplier/vendor, warehouse, transaction date, and schedule date.
- Use supplier-specific buying price lists and supplier currency where available.
- Optionally receive stock immediately by creating a linked Purchase Receipt.
- Optionally create a linked Purchase Invoice.
- Pay suppliers/vendors from the same purchase flow using POS Profile payment methods.
- Create new suppliers/vendors from POS when `Allow Create Suppliers from POS` is enabled.
- Create purchase items from POS when `Allow Create Items from POS` is enabled.
Configure the purchase feature from POS Profile:
- `Allow Purchase Order`
- `Allow Receive Stock from POS`
- `Allow Create Items from POS`
- `Allow Create Suppliers from POS`
---
### Barcode Printing
The **Barcode Printing** module prints item labels directly from POS.
- Add barcode-enabled items from the item selector.
- Choose item UOM and label quantity per row.
- Print labels or export them as PDF.
- Configure A4 label grids by rows and columns.
- Optionally include item price and batch/serial details on labels.
- Supports scale/weighted barcode generation using scale barcode settings and item/UOM barcode templates.
---
### Raw Printing With QZ Tray
Raw printing sends printer commands directly to the printer through QZ Tray instead of rendering an ERPNext HTML print format in the browser. Use it for fast thermal receipt printing, paper cutting, drawer pulses, and native label-printer commands.
Supported raw print paths:
- **Barcodes / labels**: already supported from the Barcode Printing screen using raw ZPL/EPL output for compatible label printers.
- **Invoices / POS Invoices**: supported through POS Profile raw receipt printing.
- **Sales Orders**: supported through the same POS Profile raw receipt printing flow.
- **Payment Entries / receipts**: supported through the same POS Profile raw receipt printing flow.
#### Setup
1. Install and run **QZ Tray** on each POS terminal.
2. In POS Awesome, open the QZ Tray setup dialog and connect QZ Tray.
3. Generate/download the QZ certificate from POS Awesome, trust it in QZ Tray, then restart QZ Tray.
4. Select the receipt printer and save it as the POS Profile default if this terminal should always use it.
5. Open **POS Profile** and configure:
- `Enable Silent Print`: optional for HTML QZ printing; raw receipt printing can use QZ directly without this option
- `QZ Tray Printer Name`: exact printer name detected by QZ Tray
- `Use Raw Receipt Printing`: enabled
- `Raw Receipt Width`: `42` for most 80mm printers, `32` for most 58mm printers
#### How To Use
- For invoices/orders/payment receipts, submit and print normally from POS. When `Use Raw Receipt Printing` is enabled, POS Awesome sends ESC/POS raw commands through QZ Tray without opening the browser print dialog.
- For barcode and item labels, open **Barcode Printing**, choose the label output format, and use raw ZPL/EPL for compatible thermal label printers.
- If raw receipt printing is disabled, POS Awesome keeps using the existing QZ HTML/browser print flow and POS Profile print format behavior.
- If QZ Tray is unavailable, document printing falls back to the existing browser/silent