7. Point of Sale (POS)

The Point of Sale (POS) module provides a complete retail checkout experience fully integrated with NkapBooks invoicing, inventory, and accounting systems. It is designed for shops, counters, and retail environments where fast, keyboard-driven transaction processing is essential.

7.1 POS Profiles

A POS Profile defines the configuration for a specific checkout counter. Each profile controls which warehouse to use, which accounts to debit and credit, which user is assigned, and how the interface behaves.

Schema Overview

Settings

Barcode Configuration

These fields appear only when Enable Barcodes is turned on in Inventory Settings:

Button Colour Customisation

Each POS profile allows full customisation of action button colours:

Available colour choices: Red, Orange, Yellow, Green, Teal, Blue, Indigo, Purple, Pink, Black (Grey).

SYSCOHADA Account Defaults

For businesses in OHADA member countries (Cameroon, Senegal, Ivory Coast, etc.), NkapBooks automatically maps POS Profile accounts to SYSCOHADA chart of accounts:

User Access Control

• Each POS Profile can be assigned to a specific User.
• Only the assigned user (or an Administrator / System Manager) can access the profile.
• Profiles with running sessions cannot be modified — close the session first.

7.2 POS Sessions (Shifts)

A POS Session represents a cashier's shift. It tracks all transactions (invoices, payments, and shipments) that occur during the shift and provides a reconciliation mechanism at closing.

Schema Overview

Session Amounts

Each session tracks opening, expected, closing, and difference amounts per payment method:

Opening a Session

1. Navigate to the POS Profiles Grid and select a profile.
2. The Open POS Session modal appears.
3. Enter the opening amounts for each payment method (Cash, Mobile Money, Bank).
4. Click Submit to start the session.

Behind the scenes:

• A new POSSession document is created with status Running.
• If a non-zero Cash opening amount is entered, a Journal Entry is automatically created:
  • Debit: Counter Cash Account (from POS Profile)
  • Credit: Main Cash Account
  • This transfers cash from the main cash account to the POS counter's cash drawer.

During a Session

While the session is running:

• All Sales Invoices created are flagged with isPOS: true and linked to the session via posSession.
• All Payments are recorded with isPOS: true and tracked in the session's payments table.
• All Shipments for stock-tracked items are created and tracked in the session's shipments table.
• Duplicate prevention: The system checks for already-recorded invoices, payments, and shipments before adding them to the session.

Closing a Session

1. Click the Close Shift button in the POS interface.
2. The Close POS Session modal displays all session amounts with expected values.
3. Enter the closing amounts for each payment method.
4. The system calculates difference amounts automatically (Closing − Expected).
5. Click Submit to close the session.

Behind the scenes:

• Session amounts are validated (no negative closing amounts).
• A Journal Entry is created for the cash transfer and any write-offs:
  • Cash Transfer: Debit Main Cash Account, Credit Counter Cash Account
  • Cash Shortage (negative difference): Debit Main Cash Account, Credit Write Off Account
  • Cash Surplus (positive difference): Debit Write Off Account, Credit Main Cash Account
• The session status changes to Closed.
• The application window is reloaded to return to the POS Profiles Grid.

7.3 POS Interface Features

NkapBooks uses a Modern POS layout with a split-panel design optimised for retail workflows.

Layout Overview

The POS screen is divided into two main panels:

Left Panel — Cart & Actions

Customer Selector

• A MultiLabelLink control at the top allows selecting or changing the customer (Party).
• The default customer is set from the POS Profile's Default POS Customer.
• Customer-specific pricing, loyalty points, and currency are loaded automatically.

Selected Items Table

The cart displays all items added to the current invoice:

Clicking on a row opens the Keyboard Modal for precise numeric editing of quantity, rate, or discount.

Totals Display

• Subtotal (Net Total before tax)
• Tax Amount (from applied tax templates)
• Grand Total (Net Total + Tax − Discounts)

Action Buttons

Right Panel — Item Selection

Item Search

• A text input field for searching items by name, barcode, or item code.
• Supports barcode scanning — scan a barcode and the item is automatically added to the cart.
• Weight-enabled barcode support: When configured in the POS Profile, the system extracts the item code and weight from the barcode automatically.

Item Group Filter

• A Link field that filters items by their Item Group.
• Only visible when Enable Item Group is turned on in Accounting Settings.

Item Display — Grid View vs Table View

The toggle button in the Quick Actions toolbar switches between:

Both views display real-time stock availability for inventory-tracked items. Non-inventory items (services) are also supported.

Adding Items to Cart

Items can be added via:

1. Search — Type the item name and press Enter.
2. Barcode Scan — Scan a product barcode.
3. Click/Tap — Click on an item in the grid or table.
4. Quick Quantity — Type a number before scanning/clicking to set quantity (e.g., type "5" then scan).

Stock Validation:

• For inventory-tracked items, the system validates that sufficient stock is available at the POS Profile's inventory location.
• If stock is insufficient, a validation error is displayed.
• Non-tracked items (services) can be added without stock checks.

Batch-Tracked Items:

• When a batch-tracked item is added, the Batch Selection Modal opens automatically.
• The cashier selects the batch, and stock availability is validated per-batch.

Pricing Rules:

• Unless Ignore Pricing Rule is enabled on the profile, pricing rules are automatically evaluated and applied when items are added or quantities change.
• Free items from pricing rules are added with an isFreeItem flag.

7.4 POS Payment Flow

The payment process in POS follows these steps:

Step 1 — Open Payment Modal

Click Pay (or Pay And Print) to open the Payment Modal. The modal pre-fills the amount with the invoice's Grand Total.

Step 2 — Select Payment Method

Available payment methods are loaded from the PaymentMethod table. Click a method to select it:

For Bank payments, additional fields appear:

• Reference ID — Bank transfer reference number
• Clearance Date — Expected date of fund clearance

Step 3 — Enter Amount

• The Paid Amount input is editable — the cashier can enter the exact amount paid.
• The system calculates Balance (if underpaid) or Change (if overpaid) in real-time:
  • Balance = Grand Total − Paid Amount (shown when paid < grand total)
  • Change = Paid Amount − Grand Total (shown when paid > grand total)

Step 4 — Submit Transaction

Two submission options:

Transaction Processing Pipeline

When a transaction is submitted, the following operations occur in sequence:

1. Validation — Verify invoice items, quantities, and stock availability.
2. Invoice Submission — The SalesInvoice is synced and submitted, creating accounting ledger entries.
3. Shipment Creation — If any items have stockNotTransferred, a Shipment document is created and submitted:
   • Location is set from the POS Profile's inventory.
   • Serial numbers are applied if the item uses serial number tracking.
   • The shipment is recorded in the POS session.
4. Payment Creation — A Payment document is created with:
   • isPOS: true
   • posSession linked to the current session
   • Payment method and account set based on selection
   • The payment is synced, submitted, and recorded in the POS session.
5. Session Recording — The invoice, payment, and shipment are recorded in the POS session tables.
6. Invoice Recording — The invoice (with party and grand total) is added to the session.
7. Cleanup — Cart is cleared, values are reset, and items are refreshed.

7.5 Quick Actions

The Quick Actions toolbar appears at the bottom of the right panel and provides fast access to POS features:

Loyalty Badge

When the customer has loyalty points, a yellow badge shows the point count on the Loyalty button (capped at "99+").

Coupon Badge

When coupons are applied to the invoice, a green badge shows the coupon count on the Coupon button.

Validation

Both Loyalty and Coupon actions require:

• At least one item in the cart
• A customer selected
• (For Loyalty) Customer has loyalty points > 0

7.6 Saved Invoices

The Saved Invoice Modal allows cashiers to save incomplete transactions and resume them later.

Saving an Invoice

• Click the Save button in the cart area.
• The current invoice is synced as a draft (not submitted) with isPOS: true.
• The cart is cleared, and a new invoice is started.

Resuming a Saved Invoice

1. Click the Held button (or use the keyboard shortcut).
2. The modal shows two tabs:
   • Saved — Draft invoices (not yet submitted)
   • Submitted — Submitted POS invoices with outstanding amounts
3. Use the search box to find an invoice by name.
4. Click on an invoice to load it into the cart.

Invoice Table Columns

7.7 Sales Returns

The POS supports processing returns (credit notes) directly from the checkout interface.

Opening the Return Modal

Click the Return button to open the Return Sales Invoice Modal.

Selecting an Invoice to Return

1. The modal shows all submitted POS invoices that are eligible for return:
   • Must be isPOS: true and submitted: true
   • Not cancelled
   • Not already fully returned
   • Partially returned invoices are eligible for additional returns
2. Search by invoice name using the search box.
3. Click an invoice to create a return (credit note) against it.

Return Processing

• A new Sales Invoice is created with returnAgainst set to the original invoice.
• Item quantities are negative, representing the returned goods.
• The return invoice goes through the same payment flow (refund) if needed.
• Stock is restored if inventory tracking is enabled.

Pagination

The return invoice list supports pagination (20, 40, or all items per page).

7.8 Batch Selection

When selling batch-tracked items through the POS, the Batch Selection Modal appears automatically.

How It Works

1. When a batch-tracked item is added to the cart (via search, scan, or click), the Batch Selection Modal opens.
2. The modal shows a Link field filtered to batches associated with the selected item.
3. Select the desired batch and click Select.
4. The item is added to the cart with the batch reference.
5. Stock availability is validated against the selected batch's quantity.

Validation

• If the selected batch does not have sufficient stock, a validation error is shown.
• If the item is added again, existing items in the cart are checked — quantities are aggregated per item + batch combination.

7.9 Keyboard Shortcuts

The POS is fully keyboard-navigable for fast checkout. Shortcuts are context-aware and disabled when modals are open.

Keyboard Modal

The Keyboard Modal provides a virtual numeric keypad for editing cart item values:

Quick Quantity Input

The POS supports a Quick Quantity mode for rapid scanning:

1. Type a number on the keyboard (e.g., 5).
2. Scan a barcode or click an item.
3. The item is added with the typed quantity instead of the default 1.
4. The quantity buffer resets after each item addition.

Rules:

• Only digit keys are captured (not when typing in search fields).
• If a modal is open, quick quantity input is paused.
• The quantity buffer accumulates until an item is added or a non-digit key is pressed.

POS-Specific Shortcuts

The POS registers the following keyboard shortcuts (via the useShortcuts composable):

7.10 POS Profiles Grid

The POS Profiles Grid (/pos-profiles) is the central management page for all POS configurations.

Profile Cards

Each POS Profile is displayed as a card showing:

Card Actions

Additional Actions

Permissions

7.11 Item Enquiry

The Item Enquiry feature allows staff to log customer interest in products without adding them to the cart.

Item Enquiry Form

When to Use

• Customer asks about a product that's out of stock.
• Customer wants to know when a product will be available.
• Staff wants to record demand for a product not currently in the catalogue.

7.12 Loyalty & Coupon Integration in POS

Loyalty Points

When Enable Loyalty Program is active in Accounting Settings:

1. Assign a Loyalty Program to a customer (Party record).
2. In the POS, select that customer.
3. The loyalty point balance appears as a badge on the Loyalty button.
4. Click the Loyalty button to open the Redeem Loyalty Points modal.
5. Enter the number of points to redeem.
6. Points are converted to a monetary discount using the program's Conversion Factor.

Validation:

• Cannot redeem more points than the customer has.
• The redeemed amount cannot exceed the invoice's Grand Total.
• Points must be greater than zero.

Coupon Codes

When Enable Coupon Code is active (requires Enable Pricing Rule first):

1. Click the Coupon button in Quick Actions.
2. The Coupon Code Modal opens.
3. Search and select a coupon code from the Link field.
4. The coupon is validated against its rules and applied to the invoice.
5. Applied coupons are displayed in a list within the modal.
6. Coupons can be removed by clicking the trash icon.

When a coupon is removed:

• All item-level discounts (amount and percentage) are reset to zero.
• Pricing rules are re-evaluated.

Price List Selection

Click the Price List button in Quick Actions:

1. The Price List Modal opens.
2. Select a price list from the Link field.
3. Click Save to apply it to the current invoice.
4. Item rates are updated according to the selected price list.
5. Use the trash icon to remove the price list.

Best Practices

Setting Up POS for Your Business

1. Create a dedicated Location for your POS counter (e.g., "Main Counter", "Store 1").
2. Create a POS Profile with appropriate accounts and settings.
3. Set a Default Customer (e.g., "Walk-in Customer") for quick transactions.
4. Configure Payment Methods — ensure Cash, Mobile Money, and Bank methods exist.
5. Set up a Print Template for receipts if you want custom-branded receipts.

Daily Operations

1. Open Session at the start of the day with accurate opening cash amounts.
2. Process transactions using barcode scanning and keyboard shortcuts for speed.
3. Save invoices if you need to attend to another customer.
4. Close Session at the end of the day, counting cash carefully.
5. Review the session summary to identify and investigate any discrepancies.

Handling Discrepancies

Accounting Impact

Invoice Submission

When a POS invoice is submitted, the standard double-entry accounting entries are created:

• Debit: Accounts Receivable (or Default Account from POS Profile)
• Credit: Income Account(s) for each item
• Credit/Debit: Tax Accounts (if applicable)

Payment Recording

When a payment is processed:

• Debit: Payment Account (Cash, Bank, or Mobile Money account)
• Credit: Accounts Receivable
• Outstanding amount on the invoice is updated.

Shipment

When stock is transferred:

• Stock Ledger Entries are created, deducting inventory from the POS Profile's warehouse.
• Inventory valuation is updated per the configured valuation method (FIFO or Moving Average).

Session Close — Cash Transfer Journal Entry

• Debit: Main Cash Account → receives the closing cash
• Credit: Counter Cash Account → empties the counter drawer
• Write-off entries for any positive or negative differences