Make tax engine universal — surcharges, per-category rates/discounts, more countries

[itsbkm]

Current tax logic (main/services/tax.ts) hardcodes two countries:

• India — fixed 5% for restaurant/salon, CGST+SGST split intra-state, IGST inter-state.
• Thailand — flat 7% VAT.
• Everything else — falls back to a single flat rate off product.tax_rate, no real compliance logic.

This won't scale as we add countries. Before writing more if (tenant.country === 'XX') branches, want to align on an approach — so did some homework on how other systems handle this, and where the open debates are.

How other software handles it

Odoo — taxes are data, not code. A tax is a record (name, rate, computation type: fixed/percent/division, inclusive or exclusive) attached to products or fiscal positions. Countries ship as localization modules that just install a default set of tax records + a chart of accounts for that country, rather than a special-cased code path per country. It also supports compound taxes — one tax computed on the result of another, which is exactly the shape a surcharge needs (see cess example below). (Odoo tax docs, Odoo tax customization)

Open Source POS (opensourcepos) — products belong to a tax category, and each category maps to one or more rates. That's the same "category, not product field" pattern you'd want for exemptions/reduced rates (e.g. unprepared food vs. alcohol vs. electronics) instead of a single tax_rate column per product. (opensourcepos wiki)

Open Sales Tax (self-hosted US sales tax API) — takes line items with a category field ("general", "clothing", etc.) and returns per-line jurisdiction + rate. Confirms category-based taxability, not product-based, is the norm once you leave flat-VAT countries. (open-sales-tax)

Stripe Tax / Avalara / TaxJar — the commercial end of this. Stripe assigns each product a tax category from a fixed taxonomy and a tax behavior (inclusive/exclusive/automatic), then resolves the actual rate against the customer's jurisdiction at calculation time — the product never stores a rate. TaxJar/Avalara go further with address-level ("rooftop") jurisdiction resolution for the US, where rates vary by street address, not just by state. That's out of scope for a self-hosted POS, but the category on the product, rate resolved externally separation is worth borrowing. (Stripe tax categories, tax engine comparison)

Surcharge / cess = compound tax, not a flat add-on

India's Health & Education Cess is the clean example: it's 4% of (tax + surcharge), not 4% of the sale amount. E.g. tax ₹50,000 + surcharge ₹10,000 → cess = 4% × ₹60,000 = ₹2,400. That means a surcharge/cess can't be modeled as another line at computeTaxAmount(taxType, taxableAmount, rate) against the subtotal — it needs to run against the tax already computed, i.e. a tax that takes another tax's output as its base. (cess vs surcharge, compounding example)

Current calculateItemTax has no way to express "tax on a tax" — every branch computes straight off taxableAmount. Any surcharge support needs that as a base capability, not a per-country special case.

The two real debates

1. Config-driven vs. pluggable-module vs. hardcoded-branch. Odoo's answer is "tax = data row, country = a module that seeds default data." The opposite extreme (what we have now) is a switch statement per country in application code. The middle ground — a small rules engine (base rate → optional compound surcharge → category override → inclusive/exclusive) driven by settings, with countries just supplying default config — seems to fit a self-hosted single-tenant POS better than full pluggable modules, but worth debating before committing.

2. Inclusive vs. exclusive display. Most VAT/GST countries require tax-inclusive shelf/menu pricing; US-style sales tax is exclusive by convention (add at checkout). tax_type already exists per product, so this is less of an open question for us — but it means the default for new countries needs to be right out of the box (e.g. defaulting to exclusive for a new EU country would be a compliance bug, not just a UX one). (inclusive pricing overview)

Open questions for contributors

• Do we model surcharge/cess as a new tax_type: 'compound' that references a base tax's computed amount, or a separate surcharges table keyed off tax config?
• Move tax_rate off products entirely and onto a tax_category (food / alcohol / electronics / exempt / …), with category→rate resolved per country/state at calc time?
• How many countries do we actually need in v1 beyond IN/TH — is there a shortlist (US, EU/VAT, UK, SG, etc.) worth targeting first?
• Where does per-state/province variation (US sales tax, Canadian GST/PST) fit — is that in scope for a self-hosted single-location POS, or do we punt on it explicitly?

Related code: tax.ts, countries.ts

[ericlakich]

Check out https://zip.tax ... we can make this easy for you :)

[itsbkm]

Thanks for the pointer, @ericlakich — appreciate you taking a look.

We're going to hold off on wiring in an external tax-rate API like zip.tax, though. FloCafe is FOSS specifically because we want small business owners to be able to self-host this without a recurring per-lookup or per-transaction cost stacked on top — a paid third-party dependency for something as core as tax calculation runs against that goal and would make it unfeasible for exactly the businesses we're building this for.

The plan instead is to build the taxation system out in-house, brick by brick, as a proper rules engine (base rate → compound surcharge → category override → inclusive/exclusive) driven by config data rather than hardcoded per-country branches — roughly the Odoo/opensourcepos model described above. Community contributions adding new country configs are very welcome.

We're not ruling out an optional integration with a service like zip.tax down the line (e.g. for US "rooftop"-level jurisdiction resolution, which genuinely needs an external data source), but that would be opt-in for whoever wants it — never a default, never something that locks self-hosters into a vendor or a pay-as-you-go model. If a client specifically needs that and there's real community interest (a few 👍 on a dedicated issue), we'd revisit it as an optional add-on, not baked into core.

[itsbkm]

Closing the loop on the open questions above — after a full design pass, the tax engine architecture is finalized and Phase 1 has landed.

Spec: docs/tax-engine-v2-spec.md (added in c978386). Covers, among other things, the questions raised in this issue:

• Surcharge/cess as compound tax — a rule can declare baseRuleIds referencing other rules applied to the same line (e.g. a cess computed on tax + surcharge), resolved via an acyclic, line-local dependency graph.
• Category vs. per-product rate — products/add-ons resolve to a tax_category_id through a documented six-step precedence (transaction exemption → transaction override → merchant override → explicit → inherited-parent → country-pack default → unclassified), replacing the flat product.tax_rate model.
• How many countries in v1 — a small set of official, signed country packs bundled with the installer (India, Thailand to start), plus a generic/local pack for manual configuration; more countries land as pack data, not code branches.
• Per-state/province variation — in scope for pack data (e.g. India's CGST/SGST/IGST split) when it's deterministic and computable offline from known transaction data. Anything needing external resolution, credentials, or licensed datasets (e.g. US address-level "rooftop" tax) is explicitly out of pack scope and belongs to the feat(architecture): define country and provider plugin system #142 plugin system instead.

Implementation: Phase 1 (schema + engine, additive and non-breaking) landed in 60a61d1 — main/services/tax-engine.ts, bundled main/tax-packs/{in,th,generic}.json, DB migrations v35-v37, and main/services/tax.ts now delegates to the new engine only when a product has tax_category_id set. Every existing product falls through to the original IN/TH/default switch completely untouched, so no existing install's tax behavior changes yet. Full test suite (including a new upgrade-path fixture and tax-engine unit tests) passes.

Product-facing UI (Settings → Tax, product categorization, checkout wiring), signed pack download/activation, and receipts/reports are separate follow-up phases, not part of this change.

If anyone sees a gap in the spec or the Phase 1 implementation, flag it here — happy to adjust before the next phase builds on top of it.