Project 3: Pricing Engine

Build an auditable pricing waterfall that combines list pricing, discounts, floor checks, and approval triggers.

Quick Reference

Attribute	Value
Difficulty	Level 3 (Advanced)
Time Estimate	2-3 weeks
Main Programming Language	Python (Alternatives: TypeScript, Java, Go)
Coolness Level	Level 3
Business Potential	4. Open Core Infrastructure
Prerequisites	Projects 1-2, business math, deterministic testing
Key Topics	Waterfall sequencing, discount stacking, margin governance

1. Learning Objectives

Implement deterministic pricing stages from list to net.
Support tiered and volume models without ambiguity.
Enforce margin guardrails with explainable approval triggers.
Produce pricing traces suitable for finance audits.

2. All Theory Needed (Per-Concept Breakdown)

Concept A: Price Waterfall Semantics

Fundamentals A price waterfall defines stage order and is the backbone of reproducible pricing behavior.

Deep Dive into the concept Separate percentage and absolute adjustments, define rounding policy per stage, and persist every delta with rule evidence. Treat floor checks as policy gates, not display warnings.

How this fit on projects Primary for this project; reused in P05-approval-workflow-orchestrator.md and P09-pricing-rules-dsl.md.

Definitions & key terms

Waterfall stage
Stacking policy
Margin floor

Mental model diagram

List -> Contract -> Segment -> Promo -> Manual -> Floor Check -> Net

How it works

Resolve price list version.
Apply staged adjustments.
Compute margin.
Trigger approval if guardrail breach.

Minimal concrete example

list=100000
contract=-10%
promo=-3000
manual=-4%
net=79200, floor=80000 => approval_required

Common misconceptions

“Discount percentages can be added directly.” Not always.

Check-your-understanding questions

Why enforce explicit stage order?
Why include floor checks late in the waterfall?

Check-your-understanding answers

To prevent hidden precedence variation.
Because final concessions can breach guardrails.

Real-world applications Enterprise SaaS quoting, deal desk automation.

Where you’ll apply it This project and P09-pricing-rules-dsl.md.

References

Microsoft discounting methods docs.
Oracle CPQ pricing scripting notes.

Key insights Pricing correctness is policy sequencing plus evidence quality.

Summary A deterministic waterfall is required for trust, audit, and scale.

Homework/Exercises to practice the concept Model three discount overlap scenarios and compare outcomes.

Solutions to the homework/exercises Build fixed fixtures and assert expected net totals per stage.

3. Project Specification

3.1 What You Will Build

A pricing service that calculates quote totals and emits a full waterfall trace.

3.2 Functional Requirements

Resolve effective-dated price lists.
Apply contract, segment, promo, and manual discounts.
Compute margin percentage and floor checks.
Emit approval intent when thresholds are crossed.

3.3 Non-Functional Requirements

Performance: p95 under 250ms for 100 line items.
Reliability: deterministic outputs across replays.
Usability: clear explanation of applied discounts.

3.4 Example Usage / Output

$ cpq price calculate --quote Q-2026-0120
net_total=29990
approval_required=true reason=margin below 24%

3.5 Data Formats / Schemas / Protocols

PriceList(versionId, currency, lineRates...)
DiscountRule(id, stage, condition, action)
PricingTrace(stage, ruleId, delta, runningTotal)

3.6 Edge Cases

Missing cost data for margin checks.
Overlapping promotions.
Multi-currency rounding differences.

3.7 Real World Outcome

3.7.1 How to Run (Copy/Paste)

$ cpq pricing seed fixtures/pricing_v1.json
$ cpq price calculate --quote fixtures/quote_large.json

3.7.2 Golden Path Demo (Deterministic)

Same quote fixture should always produce same stage totals and same approval status.

3.7.3 If CLI: exact transcript

$ cpq price calculate --quote Q-2026-0120
[stage] list_total=38000
[stage] contract=-3800
[stage] segment=-1710
[stage] promo=-1500
[stage] manual=-1000
[result] net_total=29990 margin=21.4 approval_required=true

4. Solution Architecture

4.1 High-Level Design

Quote Inputs -> Pricing Context Resolver -> Waterfall Engine -> Policy Guard -> Trace Store

4.2 Key Components

4.4 Data Structures (No Full Code)

PriceContext { quoteId, currency, segment, contractTier }
WaterfallStageResult { stage, delta, runningTotal, ruleIds }

4.4 Algorithm Overview

Build pricing context.
Execute stage pipeline.
Apply guardrails.
Persist trace and response.

Complexity: O(n * s) where n lines and s stages.

5. Implementation Guide

5.1 Development Environment Setup

$ cpq seed --scenario pricing-engine
$ cpq test --suite pricing-golden

5.2 Project Structure

pricing-engine/
  src/
    context/
    waterfall/
    guardrails/
  tests/
  fixtures/

5.3 The Core Question You’re Answering

“Can pricing be both commercially flexible and operationally predictable?”

5.4 Concepts You Must Understand First

Waterfall order
Margin calculations
Rounding policies

5.5 Questions to Guide Your Design

Where do you round values?
How do you explain each discount to sellers?

5.6 Thinking Exercise

Compare tiered vs volume pricing for quantity 120 on same SKU.

5.7 The Interview Questions They’ll Ask

How do you design discount stacking?
How do you enforce margin controls?
How do you reconcile CPQ totals with ERP?

5.8 Hints in Layers

Hint 1: stage order as config, not hardcoded scattered logic.
Hint 2: trace every stage delta.
Hint 3: use fixtures for regression.

5.9 Books That Will Help

| Topic | Book | Chapter | |——-|——|———| | Policy boundaries | “Clean Architecture” | Ch. 20-23 | | Tradeoff design | “Fundamentals of Software Architecture” | Ch. 5-8 |

5.10 Implementation Phases

Phase 1: context and stage model.
Phase 2: waterfall execution.
Phase 3: guardrail + approvals.

5.11 Key Implementation Decisions

6. Testing Strategy

6.1 Test Categories

6.2 Critical Test Cases

Overlapping promo + contract discounts.
Margin floor breach.
Multi-currency rounding.

6.3 Test Data

Use quote_small.json, quote_medium.json, quote_large.json with golden snapshots.

7. Common Pitfalls & Debugging

7.1 Frequent Mistakes

7.2 Debugging Strategies

Replay quote with fixed context snapshot.
Compare stage-by-stage deltas against baseline.

7.3 Performance Traps

Avoid repeated context lookups per line item; cache within run.

8. Extensions & Challenges

8.1 Beginner Extensions

Add discount reason labels.
Add stage-level visualization.

8.2 Intermediate Extensions

Multi-currency support.
Regional floor policies.

8.3 Advanced Extensions

Monte Carlo scenario simulation.
Dynamic promotion optimization sandbox.

9. Real-World Connections

9.1 Industry Applications

SaaS annual subscription pricing.
Complex enterprise bundle pricing.

OpenAPI contracts for pricing APIs.
Apache Calcite expression patterns.

9.3 Interview Relevance

Shows ability to encode policy-heavy business logic safely.

10. Resources

10.1 Essential Reading

Microsoft Learn product discounting docs.
Oracle CPQ pricing release notes.

10.2 Video Resources

Pricing strategy and RevOps architecture talks.

10.3 Tools & Documentation

OpenTelemetry for trace instrumentation.

Previous: Project 2
Next: Project 5

11. Self-Assessment Checklist

I can explain every stage in my waterfall.
I can reproduce net totals from trace data only.
I can justify approval triggers from guardrail policies.

12. Submission / Completion Criteria

Minimum Viable Completion:

Waterfall runs end-to-end.
Pricing trace includes all deltas.

Full Completion:

Margin guardrails and approval triggers work.
Regression fixtures pass.

Excellence (Going Above & Beyond):

Simulation tooling for rule change impact before publish.