Docs / Tax Rates

Tax Rates Module

The Tax Rates module is the shared tax catalog for Vendventory. It lets the admin create reusable flat or percentage tax rules, mark whether they apply to POS, Purchases, or both, define a default rule, and control whether the rule is active for new transactions.

Use this module when the same tax logic repeats: instead of typing the same tax again and again in POS or Purchases, create it here once and reuse it wherever it applies.

What the module controls

Core behavior

Name and code: human-readable and reference-safe identity for the tax rule.
Calculation type: percentage or flat amount.
Value: the percentage or currency amount applied when the rule is selected.
Scope: whether the rule appears in POS, Purchases, or both transaction areas.
Default: whether this should be the first shared tax rule selected in supported forms.
Active state: whether the rule is available for new transactions.
Sort order and description: display order and internal documentation.

Screen-by-screen breakdown

Tax Rates index

Purpose: browse and manage all shared tax rules.
What appears here: total, active, default, POS, and Purchases metrics, plus table rows showing tax rate, calculation, scope, default status, active status, linked sales, linked purchases, and update date.
Filters: search, status, scope, calculation type, and sort order.
Actions: create, edit, delete, and bulk delete.

Create and edit form

Basic details: name, code, calculation type, value, and description.
Application and behavior: available in POS, available in Purchases, make default shared tax rule, active and selectable, and sort order.
Save flow: the form uses the app's AJAX + SweetAlert + toastr contract instead of a full-page submit.

Field rules and validation

Important validation rules

Unique name and code: duplicate tax-rate identity is blocked.
At least one scope: a tax rule must apply to POS, Purchases, or both. It cannot be saved with both scopes turned off.
Percentage cap: percentage tax rules cannot exceed 100.
Active-only usage: inactive tax rules are rejected by POS and Purchases validation for new transactions.

How it connects to POS and Purchases

POS behavior

Only active rules marked for POS appear in the terminal.
The default active POS rule is preselected when one exists.
The cashier can clear the shared rule and use manual tax type and tax value for one sale.
Completed sales store tax_rate_id, tax_type, and tax_value.

Purchases behavior

Only active rules marked for Purchases appear in purchase create and edit.
The default active purchase rule is preselected when one exists.
The receiver or buyer can clear the shared rule and use manual tax input for one invoice.
Purchases store tax_rate_id, tax_type, and tax_value, and the invoice HTML/PDF shows the applied tax details.

How to add, disable, or remove tax

Operational meaning of add or remove

Add tax: create a new rule here and mark where it should apply.
Temporarily remove from new transactions: set the rule inactive. It stops appearing in POS and Purchases for new entries.
Delete completely: remove the rule from the catalog. Existing sales and purchases keep their stored tax_type and tax_value; the tax-rate link itself becomes detachable because transactions do not depend on the catalog row forever.
Per-transaction exception: leave the shared rule alone and use manual tax entry on the specific POS sale or purchase that needs a different amount.

Best practices

Recommended operating pattern

Create one clean shared rule for each real business tax scenario instead of many nearly identical duplicates.
Use stable codes so invoices, receipts, imports, and audit references remain understandable.
Mark a rule as default only when most POS or purchase transactions should start with it.
Prefer inactivation over deletion when a rule may be needed for historical review or later reactivation.
Use manual override only for exceptions, not for everyday tax entry.

What shows where after a tax rule is used

Visible downstream effects

POS terminal: selected rule, tax type, and tax value drive the checkout totals.
Sales: tax metadata is stored on the sale for review, receipts, and later operational analysis.
Purchases: the shared rule affects taxable totals and appears on invoice HTML and PDF.
Documentation and review: the same tax module now supports both the inbound purchase flow and the branch POS flow.

Tax module media placeholders

Tax-rate capture checklist

Image Placeholder

Tax Rates index with metrics and scopes

Show at least one shared rule, one POS-only rule, and one Purchases-only rule so scope behavior is obvious.

Image Placeholder

Create tax rate form

Capture name, code, calculation type, value, scope checkboxes, default toggle, active toggle, and sort order together.