First Pricing Framework

Pricing in a multi-division carrier usually lives in four places at once. Truckload prices off a cost sheet, brokerage off the spot board, dedicated off a capital model and warehousing off square footage, and none of them agree on what a margin is or who may approve a thin one. Discounts get negotiated deal by deal, and nobody can say afterward which concessions paid for themselves.

The name is literal. This is where the first price comes from: the initial quote on a lane, the first landed cost of an imported item or the first finished cost of a manufactured one, the number every later negotiation, approval and margin review is measured against. I built the platform around a single rule: every quote, in every division, is built and explained the same way. Activity-based operating cost, then the network adjustment for repositioning and backhaul, then Canada, United States and Mexico border costs, then the risk premiums for fuel, currency, tariff-driven volume loss and carrier buy rates, then margin, then market positioning, with the fuel surcharge shown separately. Each premium names the contract term that removes it, so a negotiation becomes a trade of terms rather than a haggle over a number.

Around that waterfall sit the parts that make it an operating system rather than a calculator: a governance layer that decides who may approve what, a bid workflow that takes an RFP from intake to implementation, profitability analytics that check whether the prices that were approved are the prices that were billed, and a pass-through study that turns a tariff increase into a selective, governed price plan for each SKU and customer segment instead of one blunt percentage.

A discount that cannot name the risk it gives back is not a pricing decision. It is a leak.

The platform is a Python package with typed Pydantic models from end to end. Every policy number, from margin floors and segment flex to approval limits, rule thresholds, cost-model parameters and service standards, lives in a versioned YAML configuration that a company overrides rather than edits, and every governance decision records the policy version that produced it. Adding a division is a configuration change; adding a new pricing method is one cost model and one basis builder, because the waterfall, optimizer, approvals, profitability and reporting layers do not know which method they are handling.

The same facade drives three surfaces. A command-line tool prices a lane, prints reports and runs an end-to-end demonstration on synthetic data. A FastAPI service exposes quotes, bids, approvals, profitability, renewals and the audit trail. Browser forms for product costing and bulk CSV import persist items and costings in SQLite so a team can share one running instance. The executive dashboard is a single self-contained HTML file with inline SVG charts and light and dark themes. The dashboard, the costing form and the bulk import run in English and French: the engine works in English and a translation layer at the edge renders labels, warnings, policy flags and findings in French with French number formatting, while a test fails the build if a covered scenario produces a sentence the catalog cannot translate. The pass-through study is a command-line and API workflow whose report is in English for now.

Duty rates come from live government sources rather than a bundled table: a connector to the U.S. International Trade Commission HTS REST API and another to the CBSA Customs Tariff API that also brings in excise and GST codes, each parsing defensively and reporting what it cannot read instead of guessing. A suite of 162 tests covers the cost models, risk premiums, optimizer, policy rules, segregation of duties, audit-chain verification, the full bid lifecycle, Incoterms allocation, excise and GST codes, both tariff connectors, the pass-through study and the French translation.

Every number bundled with the platform is synthetic or illustrative: cost parameters, margin targets, market rates, fuel prices, exchange rates, distances, tariff scenarios and customers. They exist to exercise the code and to make the demonstration readable. None of them is a market fact, and the defaults have to be replaced with the company's own cost accounting, plan and licensed market data before a single real quote leaves the building.

Several modelling choices are assumptions, stated as configurable parameters rather than hidden constants: how quickly contract rates follow spot, how volume responds to a tariff, the network repositioning heuristic and the typical broker margin. Each should be validated against the company's own history. The win model in particular is only as good as the bid outcomes it is calibrated on; without a market benchmark the platform says so and falls back to cost-plus at target.

The pass-through study states its own limits. Elasticities estimated from sales history are biased toward zero where prices were raised into strong demand and away from zero where they were cut to clear stock, so they are used to rank SKUs and segments by sensitivity, and the largest increases should be tested on a sample of customers first. Volume follows a constant elasticity with no competitor reaction and no switching between substitutes, and the tariff changes in the sample are labelled illustrative and describe no real measure.

It is also honest about its production gaps. Product costing persists to SQLite, but bids, approvals, the rate book and the audit log are held in memory, the API carries no authentication yet, and money is handled as rounded floats suited to quoting and analytics rather than invoicing. Each is documented as a deliberate boundary rather than discovered as a surprise.

A pricing model that never says what it assumes will eventually be trusted for exactly the thing it got wrong.

Decision-support software. All bundled data is synthetic and illustrative. Tariff and duty figures must be confirmed against authoritative trade-policy sources before use.