System Settings Conditions & Logic

This document provides a comprehensive mapping of system settings parameters to their functional conditions, business logic rules, and data dependencies within the POS application.

VAT System

Invoice-wise vs Product-wise calculations and editable VAT rules.

Loyalty Program

Card types, discount configurations, and point-to-cash redemption caps.

Serialization

Daily resets, limits, and deferred numbers for online orders.

Checkout & Delivery

Order workflow gating, payment requirements, and delivery flags.

System Setting Keys Reference Table

All attributes configuration mapping and functional logic dependencies.

Key	Default / Type	Condition / Behavior	Data Dependency
is_vat_enable	0 (Boolean)	Toggles whether VAT calculations are applied system-wide. When `0`, overall VAT values default to 0.	None. Acts as master switch.
vat_type	invoice (String)	Controls the calculation methodology. • `invoice`: Calculated on invoice final total. • `product`: Calculated individually on each item.	Requires `is_vat_enable = 1`.
is_vat_editable	0 (Boolean)	Allows custom user-provided VAT amounts during checkout instead of enforcing system percentages.	Evaluated only when `vat_type = invoice`.
vat_percentage	0.00 (Float)	The flat percentage rate charged globally on invoice totals.	Evaluated when `vat_type = invoice` and `is_vat_editable = 0`.
vat_label	VAT (String)	Display tag printed on invoices and shown on screens (e.g. VAT, GST, Sales Tax).	None.
service_type	token (String)	Determines active service layout workflow. • `token`: Queues customers using dynamic tokens. • `table`: Assigns order tickets to tables.	Controls front-end POS screen layouts.
is_sale_pay_first	0 (Boolean)	Enforces payment validation during sale creation. When `1`, orders cannot be saved with a outstanding due balance.	Validates that the sum of payment entries matches or exceeds `final_amount`.
is_pending_delivery	0 (Boolean)	Sets the default delivery state of newly created sales. If `1`, order is saved as `Pending`. Else, `Delivered`.	Determines subsequent inventory stock deduction timing.
is_show_serial sale_serial_limit	0 (Boolean) / 0 (Int)	Governs generation of sequential sale daily transaction serials. The limit defines when the daily serial resets back to 1.	Resets based on branch and transaction date. Deferred for WEB orders.
membership_card_type	0 (Integer)	Controls active loyalty benefits. • `0`: Disabled / None • `1`: Discount Percent only • `2`: Points Earn/Redeem only • `3`: Both Discount & Points	Requires customer profile to have an active `membership_card_id`.
is_membership_point_to_cash point_cash_value max_point_use_per_invoice	0 / 0.00 / 0	Regulates point redemptions. Customers convert points to a cash discount (value multiplier), subject to a maximum cap per invoice.	Enabled when `membership_card_type` is 2 or 3, and customer profile has points.
is_kitchen_copy_enable	0 (Boolean)	Controls receipt generator. If enabled, the system prints/sends a separate duplicate duplicate token copy optimized for kitchen staff.	None.
is_sale_item_updatable	1 (Boolean)	Determines if sale items can be edited or deleted once a transaction has been saved or printed.	Governs permission checks inside `SaleUpdateRequest`.
is_branch	1 (Boolean)	Enables or disables multi-branch POS options. When disabled, defaults calculations to a single master branch.	Restricts user/stock entities scoped by branch IDs.
date_format time_format	d-m-Y / h:i A	Define the visual rendering format applied to transaction dates and times on PDF receipts and dashboards.	None. Pure formatting parameters.

1. VAT Calculation Workflows

Tax calculations are highly dynamic and vary according to the vat_type. When VAT is active (is_vat_enable = 1), calculations run under one of the two logic paths below:

VAT Type: invoice

Invoice-Wise VAT Calculation

VAT is computed once against the net total of the invoice (after subtracting all loyalty and manual discounts).

# Formula
NetAmount = Subtotal - Discount - PointDiscount
VatAmount = (NetAmount * vat_percentage) / 100

Condition: If is_vat_editable = 1, the backend accepts the client's manually provided vat_amount instead, and back-calculates the percentage.

VAT Type: product

Product-Wise VAT Calculation

VAT is calculated individually on each line-item based on the specific product's tax rules, plus any applicable addon tax rates.

# Formula
ItemVat = (UnitRate * ProdVatRate / 100) * Qty
AddonVat = (AddonRate * AddonVatRate / 100) * Qty
TotalVat = Sum(ItemVat) + Sum(AddonVat)

System Behavior: When saving, the backend overrides any globally passed invoice vat_percent or vat_amount, forcing them to 0 prior to line summing.

2. Loyalty Program & Reward Points

The loyalty program operates by binding a client's transaction to their registered membership_card_type configuration. The system supports three benefit modes:

Discount Mode (Type 1)

Applies the card's designated discount_percentage directly.
Note: This automatically overrides any custom manual discount_amount sent from the POS terminal.

Points Accumulation & Cash Redemption (Type 2)

1) Earn Point Calculation. Points are earned on the net total remaining after discount:
EarnedPoints = (Product_Amount - Discount_Amount) * points_redemption_ratio Note: This is Backend Part (Points Accumulation).

2) Point Discount Calculation (Redemption & Gating Logic)

When a customer pays using their membership reward points, the handles the discount conversion and executes multiple security gating checks to ensure financial integrity.

Step A: Prerequisites Check

Deduction is triggered only if the global setting is_membership_point_to_cash is active (1), point_cash_value is greater than 0, customer's account has membership_point balance, and the checkout request contains a positive used_points value.

Step B: Available Balance Guard

Protects against over-redemption by checking the customer's actual account balance:

if (Requested Points > Customer Available Points) {
Redeem Points = Customer Available Points;
} else {
Redeem Points = Requested Points;
}

Step C: System-Wide Limit Guard

If a transaction limit is set by the store administrator (using max_point_use_per_invoice):

if (Redeem Points > Max Allowed Points Per Invoice) {
Redeem Points = Max Allowed Points Per Invoice;
}

Step D: Points-to-Cash Formula

Converts the eligible points to an actual cash discount:

Discount Amount = Redeem Points * Cash Value Per Point

Step E: Capping & Point Refund Guard

Preventing Negative Totals: If the points' cash value is larger than the bill total, the discount is capped to exactly the remaining bill amount to prevent a negative invoice total.
Point Refund: The system automatically recalculates and refunds any unused points back to the customer's account so they are not lost:

Remaining Bill Balance = Total Bill - Regular Discounts;

if (Discount Amount > Remaining Bill Balance) {
Discount Amount = Remaining Bill Balance;
Redeem Points = Discount Amount / Cash Value Per Point;
}

Step F: Frontend Verification Check

Security Guard: To prevent data manipulation or stale data calculations, the backend compares the discount amount calculated on the server with the discount amount sent by the user's browser. If they differ by more than 0.01:
The transaction is rejected and a validation mismatch error is shown.

Combined Mode (Type 3)

Triggers both Percentage Discounts and Points Accumulation/Redemption on the same ticket.

3. Invoice & Daily Serial Number Generation

To maintain structured transaction sequencing, the system creates both an invoice_no and a daily reset serial_no.

Standard POS Orders (Retail/Dine-in)

Serials are generated instantly upon creation inside the database.

Serials are scoped by branch_id and transaction date.
The serial number restarts back to 0001 each day.
If a transaction limit is set via sale_serial_limit, the count resets to 1 once that threshold is crossed.

Online Web Orders (Deferred)

Web/Ecommerce orders defer serial number assignment to preserve sequential continuity for on-site cash registers.

Saved initially with a serial_no = null value.
Serial numbers are assigned dynamically only when the order status is updated to: Confirmed / Shipped / Delivered

4. POS Checkout & Delivery Workflows

Two settings control checkout validation and default order delivery states, functioning as gatekeepers for POS terminals:

is_sale_pay_first

When set to 1, the backend throws a validation exception if a POS ticket contains an outstanding due balance. Fully-paid transactions are enforced.

is_pending_delivery

If 1, new orders default to Pending. If 0, orders are marked as Delivered immediately, triggering immediate inventory stock deductions.