PRD: Fare & Tax Pricing Engine

Module	Pricing	PRD ID	PRD-FARE-001
Status	Ready to dev	FEAT	FARE
Epic	—	Plane	BANA-1513
Date	2026-06-05	Version	v1.0
Packages	@nx/pricing	URD	FARE
Surface	BackendClient · Owner/Mgr
Owner	Phát Nguyễn

What the Fare & Tax Pricing Engine is

Every product variant has a fare set - the container for its base fare and any conditional child fares; the system auto-creates a fare set + base fare the moment a variant appears, so every variant is priceable right away. An owner sets a parent fare under one of two strategies - OVERRIDE (always wins) or SALE (competes as a discount) - then adds child fares carrying their own price and eligibility rules (quantity, time window, and so on). The engine picks the winning fare by resolving the highest-priority tier first; within that tier an OVERRIDE fare always beats a SALE fare, and among valid fares of the same kind the lowest price wins; with no valid child fare it falls back to the base price.

Alongside that, an owner attaches percentage, fixed, or per-unit taxes to a variant's tax set, chooses inclusive (baked into the price) or exclusive (added on top), and taxes can compound on top of earlier ones in priority order. At checkout the sale flow calls one pricing simulation; the result is an immutable pricing snapshot - the applied fare and taxes per line plus order totals - so pricing is consistent and auditable every time. A line with no tax configuration still prices fine, just at zero tax - it is never blocked by missing configuration.

Why one engine is needed

Prices used to be hard-coded on the product or computed ad hoc at checkout - no consistent home for taxes, rule-based prices, or an auditable breakdown. Merchants need one engine that selects the right fare per variant, computes taxes correctly (inclusive/exclusive, compound, item-level), and returns one consistent priced result the sale flow consumes at checkout without re-implementing pricing logic. That is the foundation for reliable cost, tax, and margin reporting in the HKD/SME bookkeeping BANA targets.

The engine builds fare selection and tax computation on top of the product-variant catalog, confines every record to the user's own merchant, and exposes a pricing simulation the sale flow consumes.

One example, start to finish

Variant "White T-shirt" has a base price of 100,000 VND. The owner adds a SALE parent fare with a child fare priced at 80,000 VND, carrying the rule "quantity purchased is 10 or more". This variant's tax set attaches a 10% VAT, exclusive.

Step	What happens	Result
A customer buys 12 shirts	The engine evaluates the quantity rule: 12 ≥ 10, the child fare is valid	The 80,000 VND child fare wins, not the 100,000 VND base price
Tax is computed on the selected unit price	10% exclusive VAT, added on top	Tax per shirt = 80,000 x 10% = 8,000 VND
The pricing simulation returns the line snapshot	12 shirts, unit price 80,000 VND	subtotal 960,000 VND, tax 96,000 VND, total 1,056,000 VND
A customer buys 5 shirts (a separate order)	The quantity rule fails (5 < 10), the child fare is eliminated	The engine falls back to the base price of 100,000 VND per shirt, with no error

The easiest thing to get wrong

The base price competes at its own priority tier too

The base price doesn't automatically lose to a child fare sitting in the same priority tier. The base price defaults to priority 0; a child fare also set at priority 0 has to compete on price fairly against the base price, like any other pair - having a child fare present doesn't automatically make it win.

Conversely, when a valid OVERRIDE fare is present in the tier that is currently winning, it wins immediately, with no price comparison against anyone else in that tier - not even a cheaper SALE fare.

1. Goals & Non-Goals

Goals

• Select the winning fare per variant by resolving the highest-priority tier first: the base price competes at its own priority (0 by default); within the winning tier an OVERRIDE fare always beats a SALE fare, and with no OVERRIDE the cheapest valid fare wins, with rule evaluation (attribute, operator, value; AND logic).
• Compute taxes in priority order with percentage, fixed-amount, and per-unit-amount modes, inclusive/exclusive treatment, compound tax-on-tax, at item-level scope.
• Provide a pricing simulation that returns an immutable pricing snapshot - per-line applied fares and taxes plus order totals.
• Automatically create a fare set + base fare the moment a product variant appears, so every variant is immediately priceable.
• Price a line at zero tax when it has no tax configuration, rather than failing.

Non-Goals

• Applying promotion discounts during checkout - the discount calculator is not wired this increment (owned by the Promotions feature).
• Order-level tax computation - a merchant-wide tax set is modeled but order-level taxes are not computed in any pricing pipeline yet.
• Multi-currency pricing.
• Persisting orders, issuing invoices, or mutating stock.

2. Success Metrics

Metric	Target / signal
Pricing correctness	Checkout prices match configured fares + taxes for sampled baskets; zero discrepancies vs manual calculation
Fare coverage	100% of product variants are immediately priceable (auto-created fare set + base fare)
Snapshot integrity	Every priced order produces an immutable snapshot with a per-line fare/tax breakdown
Precision	Monetary math agrees to 4-decimal precision end-to-end

3. Personas & Scenarios

Persona	Goal in this feature
Owner / Manager	Set base and conditional prices per variant, attach taxes, control how prices are selected
Cashier	Get a correct, consistent priced result at checkout without configuring anything
System	Auto-create a fare set + base fare when a variant appears, so nothing is unpriceable

Core scenarios: an owner sets a base fare and optional rule-driven child fares + taxes per variant → at checkout the sale flow calls the pricing simulation → the engine selects the winning fare per line by priority tier, computes item-level taxes in priority order → returns an immutable pricing snapshot with per-line and order totals.

4. User Stories

#	As a	I want	So that
01	owner	to set a base price per variant and optional child prices driven by rules	the right price applies automatically
02	owner	to choose whether a child fare acts as an OVERRIDE (always taking precedence) or a SALE (competes as a discount, the cheapest qualifying price wins)	I control my pricing strategy
03	owner	to attach percentage, fixed, or per-unit taxes at item level, inclusive or exclusive, compounded where needed	totals reflect the correct tax treatment
04	cashier	checkout to return a consistent priced result for the basket	I never re-key or re-calculate prices
05	cashier	an auditable breakdown of every applied fare and tax	a disputed price can be explained
06	system	a fare set + base fare created automatically when a variant appears	every variant is immediately priceable

5. Functional Requirements

#	Requirement	Status	URD ref
FR-001	Each product variant has one fare set that holds all of its fares. The owner sets a base price (no parent, no children) as the fallback.	✅	URD-FARE-001 · URD-FARE-003
FR-002	A fare set + base fare is auto-created when a product variant appears (via a data-sync event).	✅	URD-FARE-002
FR-003	The owner creates a parent fare with one of two strategies - OVERRIDE or SALE - then adds child fares under that parent. • Each child fare carries its own price. • Each child fare carries eligibility rules (attribute, operator, value). • Every rule on a child fare must hold for that child to be valid (AND logic).	✅	URD-FARE-004 · URD-FARE-005 · URD-FARE-006
FR-004	The engine picks the winning fare by priority tier. • It narrows to the highest-priority tier among the valid child fares and the base price; the base price competes at its own priority, 0 by default. • Within that tier, if at least one valid OVERRIDE fare exists, OVERRIDE always beats SALE and the lowest-priced OVERRIDE wins. • If that tier holds no OVERRIDE, the lowest-priced fare in the tier wins.	✅	URD-FARE-007 · URD-FARE-008
FR-005	When no child fare is valid, the base price is selected.	✅	URD-FARE-009
FR-006	The owner can create tax types and a tax set, adding taxes to it in one save.	✅	URD-TAX-001 · URD-TAX-002
FR-007	A tax is computed one of three ways: percentage, fixed amount, or per-unit amount. • Taxes apply in ascending priority order. • Taxes sharing a priority form one group and are computed together.	✅	URD-TAX-003 · URD-TAX-004
FR-008	A tax is either exclusive or inclusive. • Exclusive: added on top of the price. • Inclusive: back-calculated from the price, never increasing the total. • A compound tax computes on the running total, which already includes earlier priority groups.	✅	URD-TAX-005 · URD-TAX-006
FR-009	Item-level taxes apply per line. • Taxes come from the variant's tax set; when the variant has no tax set of its own, the product's tax set is used. • A merchant-wide (order-level) tax set is modeled, but order-level taxes are not computed in any pricing pipeline.	🔶	URD-TAX-008
FR-010	A line with no tax configuration is priced at zero tax rather than failing.	✅	URD-TAX-009
FR-011	The pricing simulation returns an immutable pricing snapshot. • Per line: the selected fare and the taxes applied. • Per order: the order totals, plus a per-bearer ledger (buyer / seller).	✅	URD-CON-004
FR-012	Monetary values use 4-decimal precision throughout calculation.	✅	URD-CON-003
FR-013	Fares, fare sets, taxes, and tax sets are per-merchant data. • Every record is confined to the owner's own merchant. • Deletion is a soft-delete and is recoverable.	✅	URD-FARE-011 · URD-TAX-010

5.1 Acceptance Criteria

• Create a new product variant with a selling price → a fare set + a base fare are auto-created; the variant is priceable immediately with no further action.
• Create one OVERRIDE parent fare and one SALE parent fare, each with a valid child fare in the same top-priority tier → price that line → the OVERRIDE fare wins even though the SALE price is lower.
• A variant with a base price of 100 and a SALE child fare of 80 (rule: quantity ≥ 10) → price 12 units → the child fare of 80 wins; price 5 units → the base price of 100 wins because no rule matches.
• Create a tax set for a variant, add a 10% exclusive tax on a price of 110 → compute → tax is 11, total is 121.
• Switch that tax to inclusive → compute → tax is approximately 10, total stays 110 (back-calculated from the price).
• Add two compound taxes (10% then 5%) on a base of 100 → compute → the first tax of 10 raises the base to 110, the second is 5.5; total tax is 15.5.
• Price a line for a variant with no tax set attached → the line still prices, the tax portion is zero, no error is raised.
• Call the pricing simulation for a multi-line basket → get back an immutable pricing snapshot with per-line applied fares and taxes, plus order totals and a per-bearer ledger.
• Configure a merchant-wide (order-level) tax set and price an order → the order-level tax portion does not appear in the result; only item-level taxes are computed.
• Delete a fare, fare set, tax, or tax set → the record moves to a deleted state (soft-delete) and is no longer used for pricing, but remains recoverable.

6. Non-Functional Requirements

Area	Requirement
Data integrity	A computed pricing snapshot is immutable once produced; the breakdown is not edited after the fact
Merchant-scoped access	All fares, taxes, and records are confined to the user's own merchant and are soft-deleted (recoverable); access requires authentication
Precision	Monetary math uses 4-decimal precision; inclusive taxes never increase the total
Performance / scale	Simulation prices a full basket in one call
Fare-set consistency	Auto-creating a fare set for a new variant is guarded only by an existence check at the data-sync layer (skipped if a fare set already exists for that variant), not by a database-level constraint enforcing exactly one fare set per variant
i18n	User-facing labels are bilingual

7. UX & Flows

Configuration screens (fares, fare sets, taxes, tax sets) live in the owner-facing back office; the priced result is consumed headlessly by the sale flow at checkout.

8. Data & Domain

Concept	Role
Fare set	Container of all fares for one product variant
Fare (price entry)	A price - the base price (no parent, no children), or a parent fare (OVERRIDE/SALE) plus its children
Rule (condition)	A condition (attribute, operator, value) on a child fare; all rules must pass (AND)
Tax set	Container of taxes for a variant (item-level) or the merchant (order-level)
Tax	A percentage/fixed/per-unit charge with priority, temporal window, inclusive/exclusive/compound flags
Tax type (category)	A category (e.g. VAT) - system-wide or merchant-scoped
Pricing snapshot	The immutable result - applied fares and taxes per line, plus order totals and a per-bearer ledger

Conceptual only - full schema and invariants in the pricing domain model.

9. Dependencies & Assumptions

Depends on

#	Feature	Dependency
01	Product (variants)	Fares, tax sets, and costs are keyed to product variants; variant creation drives auto-creation.
02	Commerce / Merchant	Fares, taxes, and records are confined to the user's own merchant.
03	Product-variant creation events	The trigger that auto-creates a fare set + base fare.

Assumptions

#	Assumption	If wrong
01	Every product variant signals its creation so its fare set can be created.	A variant created without signaling gets no auto-created fare set, and that variant cannot be priced.
02	A line with no tax configuration is acceptable and priced at zero tax.	Treating missing tax configuration as an error instead of valid would block an entire transaction rather than simply computing zero tax.
03	The sale flow calls the pricing simulation at checkout rather than computing prices itself.	A sale flow that computes prices itself would drift from the pricing engine's result and break the snapshot's consistency and auditability.

10. Release Plan & Launch Criteria

Aspect	Plan
Phase	P1 (Fares + Taxes) - see URD feature catalog
Rollout	All merchants; no feature flag
Migration	None (new entities; fare sets auto-created on product-variant creation)
Launch criteria	Checkout prices match configured fares + taxes for sampled baskets; snapshot produced per order; tax inclusive/exclusive/compound math verified
Monitoring	Pricing discrepancy rate vs manual calculation, fare-creation coverage per merchant, snapshot generation errors

References

• URD: Pricing - Fares & Fare Sets · Tax Computation
• Related: Cost Tracking · Promotions & Rules · Cross-cutting requirements
• Module: Pricing - URD
• Developer: @nx/pricing · domain model · Fare System · Tax System

Risks & Open Questions

#	Risk / question	Mitigation / status
01	Promotion discount ordering vs order-level taxes in the snapshot pipeline	Open: define whether the discount calculator runs before or after order-level taxes once both are wired in
02	Missing tax configuration would leave a line untaxed	A line with no tax set is priced at zero tax rather than failing (FR-010)
03	Variant created without a fare would be unpriceable	Auto-create a fare set + base fare when a variant appears (FR-002)
04	Fare-set auto-creation is guarded only by an existence check at the data-sync layer, not a database constraint, so two coincident sync events could in theory create more than one fare set for the same variant	Open: add a database-level uniqueness constraint on the variant + activated-status pair
05	A merchant-wide (order-level) tax set can be modeled but order-level taxes are not computed in any pipeline, so a tax configured at that scope does not yet reach the order total	Open: wire order-level taxes into both pricing pipelines (FR-009)

FAQ

#	Question	Answer
01	How does the engine pick which fare wins?	It evaluates child fares against their rules, then keeps only the highest-priority tier among the valid ones (the base price competes at its own priority too). Within that tier an OVERRIDE fare always beats a SALE fare; with no OVERRIDE, the cheapest valid fare in the tier wins; if no child fare qualifies, the base price is used.
02	What is the difference between OVERRIDE and SALE?	Both are strategies of a parent fare. OVERRIDE always wins when valid, regardless of whether it is more or less expensive than another fare in the same tier. SALE competes as a discount - among valid SALE fares in the same tier, the cheapest one wins.
03	What happens if a variant has no taxes configured?	The line is priced with zero tax - it is never blocked, just untaxed.
04	Inclusive vs exclusive tax - what's the difference?	Exclusive taxes are added on top of the price; inclusive taxes are back-calculated out of the price, so an inclusive tax never increases the total.
05	Is order-level tax computed?	Not yet - a merchant-wide tax set can be modeled, but that portion is not computed in the pricing pipeline. Only item-level tax is applied today.
06	Does this engine apply promotions at checkout?	Not yet - promotions can be configured, but the discount calculator is not wired into the pricing pipeline this increment.