Pricing Phase A Built
Pricing is the engine that turns a product variant into money. It picks the winning fare (base price or a rule-driven override), layers on the right taxes, tracks what each variant costs the merchant, and runs promotions - then returns a single, consistent price for every line and the whole order. Owners configure it; the sale flow consumes it at checkout.
Status: Built · Owner: Phat · Phase: 1-3 · Last reviewed: 2026-06-05
Chain Link Roadmap Phase 1 PRD Fare & Tax Pricing Engine · Pricing simulation & preview · Promotions, methods & segment rules (catalogue) URD URD Dev docs @nx/pricing Runbook - (not yet authored) Delivery log Traceability matrix
1. Identity
| Property | Value |
|---|---|
| Module ID | CORE-14 |
| Tier | Core |
| Status | Built |
| Phase | P1 (Fares + Taxes) · P2 (Costs + Simulation v2) · P3 (Promotions + Rules) |
| Priority | HIGH |
| Primary users | Owner / Manager (configure) · Cashier (consume at checkout) |
2. Purpose & Scope
| Included | Excluded |
|---|---|
| Fare selection per product variant (default, override, rule-based child fares) | Order persistence (owned by Orders) |
| Compound, priority-ordered tax computation at item and order level | Invoice / e-invoice issuance (owned by Tax & Invoice) |
| Immutable pricing snapshots per line and per order | Stock mutation (owned by Inventory) |
| Variant cost tracking with effective date ranges | Payment processing (owned by Payment) |
| Promotions, promotion methods, and eligibility rules | Discount calculation wired into checkout (entities exist; calculator pending) |
| A pricing simulation endpoint consumed by the sale flow | Multi-currency pricing |
3. Capabilities
| Capability | What the user can do |
|---|---|
| Fare selection | Set a base price per variant and have the engine pick the winning fare automatically. |
| Rule-based pricing | Attach conditions (quantity, time window, channel) so a child fare wins only when they match. |
| Override vs discount fares | Choose whether the first matching child wins (OVERRIDE) or the cheapest valid child wins (DISCOUNT). |
| Tax computation | Apply percentage, fixed, inclusive, exclusive, and compound (tax-on-tax) taxes by priority. |
| Order-level taxes | Apply merchant-scoped taxes to the whole order, not just each item. |
| Cost tracking | Record what each variant costs over time, with effective date ranges and a current cost. |
| Pricing simulation | Get a priced result (per-line + order totals) for a basket without persisting an order. |
| Pricing snapshot (v2) | Receive an immutable, auditable breakdown of every applied fare and tax. |
| Promotions | Define promotions with a method and eligibility rules. |
| Auto fare seeding | A fare set + default fare is created automatically when a product variant appears. |
4. Module Dependencies
| Depends on | Why |
|---|---|
| Commerce | Fares, taxes, costs, and promotions are scoped per merchant. |
| Product | Fares, tax sets, and costs are keyed to product variants. |
| Used by | Why |
|---|---|
| Orders | The sale flow calls the simulation endpoint to price each line and the order at checkout. |
| Tax & Invoice | Tax breakdown feeds invoice line and total figures. |
5. Backend Packages
Implementation detail lives in the developer docs - this section only maps the module to the services that power it.
| Package | Role | Developer docs |
|---|---|---|
@nx/pricing | Owns fare selection, tax computation, cost tracking, promotions, and the pricing simulation engine; seeds fare sets from product-variant CDC. | pricing |
Engineering Mapping (Feature ⇄ Package)
The horizontal axis of the Feature Spine - each business feature (
<AREA>in the URD) maps to its engineering home.
| Feature | Dev package | Status |
|---|---|---|
FARE Fares & Fare Sets | @nx/pricing | Built |
TAX Tax Computation | @nx/pricing | Built |
COST Cost Tracking | @nx/pricing | Built |
SIM Pricing Simulation & Preview | @nx/pricing · @nx/sale | Built |
PROMO Promotions & Rules | @nx/pricing | In-progress |
6. Key User Flows
Configure a Variant Price
Price at Checkout
Auto-seed a Fare Set
7. Roles & Permissions
| Role | Can | Cannot |
|---|---|---|
| Owner / Manager | Create and manage fares, fare sets, taxes, tax sets, costs, promotions, and rules; run simulations. | Edit pricing snapshots after they are computed. |
| Cashier | Trigger a price simulation at checkout (read result). | Mutate fares, taxes, costs, or promotions. |
| System | Seed a fare set + default fare on product-variant CDC events. | - |
8. Status & Roadmap
| Phase | Capabilities |
|---|---|
| P1 | Fares, fare sets, parent/child hierarchy, rule-based selection, taxes, tax sets, tax types, compound/inclusive tax computation. |
| P2 | Variant cost tracking with date ranges, pricing simulation (v1 + v2), immutable pricing snapshots. |
| P3 | Promotions, promotion methods, eligibility rules, and a discount calculator wired into the checkout pipeline. |
Promotion and Rule entities and CRUD ship today, but the discount calculator is not yet wired into either simulation pipeline - promotions are therefore classified In-progress.