A Frappe/ERPNext application with specialized tools for retail operations.
Executive business-owner dashboard powered by Apache ECharts 5 combining financial statements, real-time sales & POS metrics, inventory health, operational alerts, and a comprehensive indicators table.
Route: /app/store-dashboard
- Financial ECharts:
- Balance General (
bar-stack): Left stacked bar for Activo (Efectivo y Bancos,Cuentas por Cobrar,Inventario,Otros Activos) and right stacked bar for Pasivo y Patrimonio (Cuentas por Pagar,Otros Pasivos,Capital,Utilidad Acumulada y Ejercicio) with equal bar width. - Estado de Resultados (
Waterfall+ Expense Breakdown): TracksIngresos -> Costo de Ventas -> Utilidad Bruta -> Gastos Operativos -> Utilidad Netaand top expense accounts.
- Balance General (
- Commercial & Inventory ECharts:
- Daily Sales, Gross Profit & Margin % trend (
Mixed Line & BarwithdataZoom). - Sales by Item Group (
Nightingale Rose). - Top 10 Products (
Horizontal Barswitchable between Revenue, Gross Profit, and Units). - Payment Methods breakdown (
Doughnut). - Sales Heatmap by Day of Week & Hour (
Heatmap). - Capital in Stock (Cost) vs. Sales by Category (
Grouped Bar).
- Daily Sales, Gross Profit & Margin % trend (
- Operational Alerts & Executive Indicators Table:
- Low-stock best-sellers alert and dead stock (+60 days without sale) table.
- Final 13-indicator table covering Profitability, Liquidity & Solvency, and Inventory/Operations.
Complete dashboard page for quick product information lookup.
Route: /app/item-inspector
- Barcode - Camera scanning or manual entry
- Item Code - Link field with autocomplete
- Multi-match - Selector when multiple items share the same barcode
- Name, code, group, brand, UoM
- Product image
- Description (plain text, no HTML)
- Status tags: DISABLED, Not a stock item
| Indicator | Description |
|---|---|
| Total Stock | Sum of quantities across all warehouses |
| Estimated Cost (stock) | Total inventory value |
| Current Price | Price from selected price list (updates dynamically) |
| Sales 30 Days | Sales amount with unit and invoice details |
| Profit Margin | Percentage with color coding (green ≥20%, yellow ≥10%, red <10%) |
| Days Without Movement | Days since last sale (green <30, yellow 30-59, red 60+) |
| Last Sale | Total amount with unit and unit price details |
| Last Purchase | Total amount with unit and unit cost details |
⚠️ Low Stock - When stock < reorder level- ⏰ No Sales 60+ Days - Possibly obsolete product
- Price list selector
- Interactive price evolution chart
- Table with last 10 price changes
- Price and margin update when changing price list
- Current, reserved, and projected quantities
- Valuation cost per warehouse
- Estimated value by location
- Last 10 sales with document link
- Last 10 purchases with document link
- Open Item - Go to product form
- Balances - Filtered Stock Balance report
- Movements - Filtered Stock Ledger report
Simplified version for quick lookups.
Route: /app/item-inspector-light
Features:
- Only 3 KPIs: Stock, Estimated cost, Current price
- Price history (chart and table)
- No navigation buttons
- Minimalist design
Dashboard page for quick customer information lookup.
Route: /app/customer-lookup
- Search by customer code, name, phone, or email
- Quick selection from search results
- Name, customer group, territory
- Mobile phone and email (when available)
- Primary address
| Indicator | Description |
|---|---|
| Outstanding Balance | Total unpaid amount from Sales Invoices |
| Lifetime Value | Total purchases with invoice count |
| Last Purchase | Date of most recent transaction |
| Loyalty Points | Current points balance (if Loyalty Program is enabled) |
- Last 10 sales invoices with document links
- Invoice status, date, and amounts
- Sales User, Sales Manager, System Manager, Administrator, Accounts User
Generate product catalogs for printing or digital distribution.
Route: /app/catalog-generator
- Item Group - Filter by group (includes child groups)
- Brand - Filter by brand
- Warehouse - Filter by items with stock
- Price List - Price list for pricing
- Include Disabled - Option to include disabled items
- Column selection (2, 3, or 4 columns)
- Responsive grid layout
| Option | Description |
|---|---|
| Show Barcode | Display barcode text |
| Show Barcode Image | Display barcode image |
| Show Price | Display item price |
| Show Description | Display item description |
| Group by Item Group | Organize items by category |
- HTML preview for printing
- PDF-ready layout
- System Manager, Sales Manager, Sales User, Stock Manager, Stock User
Generate barcode labels for printing.
Route: /app/label-generator
| Format | Size | Columns |
|---|---|---|
| 2x1 in | 50.8×25.4mm (2×1") | 1 column (thermal roll) |
| Small | 38×25mm | 4 columns |
| Medium | 50×30mm | 3 columns |
| Large | 70×40mm | 2 columns |
- Add items by barcode or item code
- Specify quantity per item
- Primary and optional secondary Price List support
- Dynamic font sizing based on format
- Dynamic barcode height and EAN-8 / EAN-13 / CODE128 rendering
- Price display toggle
- Load items with stock (with warehouse filter)
- Print-ready HTML output (including
@page { size: 2in 1in; }for thermal label rolls)
- System Manager, Stock Manager, Stock User, Sales User
Review an Excel purchase template, preview and edit UoM and Item Group per row, create or update Items and selling Item Prices (up to two price lists), and submit a single Purchase Invoice (update_stock=1, is_paid=0) in one atomic transaction.
Route: /app/carga-compras
- Downloadable 7-column Excel template (
Codigo Producto,Producto,Codigo de Barra,Cantidad,Costo,Precio Venta 1,Precio Venta 2) and support for equivalent headers (including PACC templates whereCodigo de Barraacts asitem_codeandbarcode,Costo +envio,PrecioMayorista,PrecioDetalle) - Preserves product codes and barcodes as exact text
- Server-side preview with dry-run ERPNext validation (
savepointrollback) - Row-level editing of
item_groupandstock_uom(with automatic read-only lock onstock_uomif an existing item has stock movements) - Creates/updates selling
Item Pricerecords withvalid_from = today()without duplicating same-day records - Single atomic transaction for Items, Item Prices, submitted
Purchase Invoice(update_stock=1), and attached.xlsxfile - Idempotent confirmation via unique
upload_idand stale preview protection (preview_token)
- System Manager, Purchase Manager, Purchase User, Stock Manager, Accounts Manager
Custom print format for POS Closing Entry documents, optimized for thermal receipt printers.
DocType: POS Closing Entry
- Optimized for thermal printers
- Monospace font (Courier New) for alignment
- Compact design with dashed section dividers
| Section | Content |
|---|---|
| Header | Company name, document ID, POS profile, user, period dates |
| Sales Summary | Transaction count, item quantity, net total, grand total |
| Payment Methods | Opening amount, expected amount, closing amount, difference (color-coded) |
| Transactions | List of all POS invoices with customer, date, amount, and return badge |
| Footer | Cashier signature line, print timestamp |
- Color-coded payment differences (green for positive, red for negative)
- Return transactions marked with "RET" badge
- Automatic currency symbol from company settings
- Print-ready CSS with proper margins
cd $PATH_TO_YOUR_BENCH
bench get-app https://github.com/ernestoruiz89/retail_tools
bench install-app retail_tools
bench build --app retail_tools
bench restart- Frappe Framework v15+
- ERPNext v15+
- Python 3.10+
| Page | Navigation | Direct URL |
|---|---|---|
| Item Inspector | Modules > Retail Tools > Item Inspector | /app/item-inspector |
| Item Inspector Light | - | /app/item-inspector-light |
| Customer Lookup | Modules > Retail Tools > Customer Lookup | /app/customer-lookup |
| Catalog Generator | Modules > Retail Tools > Catalog Generator | /app/catalog-generator |
| Label Generator | Modules > Retail Tools > Label Generator | /app/label-generator |
| Carga de Compras | Modules > Retail Tools > Carga de Compras | /app/carga-compras |
- By barcode: Enter the code and press Enter
- By Item Code: Use the "Product" Link field
- With camera: Click "Scan with camera" (requires HTTPS)
- Enter customer name, code, phone, or email
- Select from search results
This app uses pre-commit for formatting and linting:
cd apps/retail_tools
pre-commit install- ruff - Python linter and formatter
- eslint - JavaScript linter
- prettier - Code formatter
retail_tools/
├── retail_tools/
│ ├── retail_tools/
│ │ └── page/
│ │ ├── item_inspector/ # Full product lookup
│ │ │ ├── item_inspector.py # Backend API
│ │ │ ├── item_inspector.js # Frontend
│ │ │ └── item_inspector.css # Styles
│ │ ├── item_inspector_light/ # Simplified version
│ │ │ ├── item_inspector_light.py
│ │ │ ├── item_inspector_light.js
│ │ │ └── item_inspector_light.css
│ │ ├── customer_lookup/ # Customer lookup
│ │ │ ├── customer_lookup.py
│ │ │ ├── customer_lookup.js
│ │ │ └── customer_lookup.css
│ │ ├── catalog_generator/ # Product catalog
│ │ │ ├── catalog_generator.py
│ │ │ ├── catalog_generator.js
│ │ │ └── catalog_generator.css
│ │ └── label_generator/ # Barcode labels
│ │ ├── label_generator.py
│ │ ├── label_generator.js
│ │ └── label_generator.css
│ ├── hooks.py
│ └── patches.txt
├── pyproject.toml
└── README.md
| Endpoint | Description |
|---|---|
resolve_item_from_barcode(barcode) |
Resolves barcode to Item |
get_item_snapshot(item_code) |
Returns complete product snapshot |
| Endpoint | Description |
|---|---|
search_customer(query) |
Search customers by code, name, phone, email |
get_customer_snapshot(customer) |
Returns complete customer snapshot |
| Endpoint | Description |
|---|---|
get_items_for_catalog(...) |
Get filtered items for catalog |
generate_catalog_html(...) |
Generate catalog HTML for preview/print |
| Endpoint | Description |
|---|---|
get_label_formats() |
Get available label formats |
get_item_for_label(item_code) |
Get item data for label |
get_items_with_stock(warehouse) |
Get items with stock |
generate_labels_html(items, format) |
Generate labels HTML for printing |
| Endpoint | Description |
|---|---|
get_initial_data(company) |
Get initial defaults, site settings, and user permissions |
download_template() |
Download the 7-column .xlsx template |
preview_purchase_upload(...) |
Parse and validate the .xlsx file and simulate ERPNext submission |
confirm_purchase_upload(...) |
Atomically create/update Items, Item Prices, and submit the Purchase Invoice |
MIT