Filter carrier rates on the promise, then sort on billed cost

An order for Dhaka leaves a New Jersey warehouse on 22 October: the seller listed the item at 1.8 kg in a 30 by 25 by 20 cm box, and checkout promised delivery by 29 October. Four carriers return nine services. The cheapest headline rate is 3,180 US cents on an economy service estimated at eleven days; the cheapest service that keeps the promise is 4,960 cents, and bills 5,610 once the residential surcharge lands. This playbook builds a rate service that picks the 5,610 cent service on purpose, and the rule it defends is that rate shopping is a filter on the promise, then a sort on billed cost: a sort on the headline rate picks a service the invoice corrects weeks later.

Measure the parcel before you ask for a rate

Carriers bill the greater of actual weight and volumetric weight, and volumetric weight is the box volume divided by a divisor the carrier publishes for that service. A rate requested on the seller's listed dimensions is a rate for a parcel that does not exist. The carrier re-weighs at its hub, bills the difference as an adjustment line on a later invoice, and the service you chose as cheapest turns out not to have been. The quote you show at checkout can come from a rate card; the quote that decides the carrier must come from the parcel on the bench.

Have the warehouse scale and dimensioner write actual_weight_g, length_mm, width_mm, height_mm and measured_at onto the parcel row, and make the rate service reject a request whose measured_at is null. Compute the billable weight per service before the request: with the box measured at 32 by 27 by 22 cm and a divisor of 5,000 cubic cm per kg (an example figure; take each carrier's from its rate guide and store it with a version id), the volumetric weight is 3,802 g against 1,800 g actual, and the service's 500 g rounding step makes it 4,000 g billable. Store billable_weight_g on every quote so the invoice match in step six has something to compare against.

You know this worked when the carrier's weight adjustments on the invoice fall to the odd parcel instead of a share of every batch.

Store one quote row per service, from one request shape

Every carrier gets the same parcel, origin, destination, declared value and ship date, so the quotes that come back are comparable. A quote that lives only in a log line cannot be bought against, matched to the invoice or explained to the customer who asks why their parcel went by the slower carrier. So the rate service writes a row per service before any ranking runs, and writes a row with status = 'error' for a carrier that timed out, so a missing carrier is visible rather than silently absent from the choice.

Keep the carrier's raw response on the row as well, and convert a quote returned in another currency at a stored FX rate id while keeping the original amount. You know this worked when, for any shipment, you can list every service that was considered and the reason each losing one lost.

Filter on the promise and the limits before you look at price

The order carries promised_by, the date checkout showed the customer, and a service that cannot meet it is not a candidate at any price. The same goes for a service whose maximum weight, maximum length or length plus girth the parcel exceeds, a service that does not deliver to the destination postcode, and a service that will not carry the contents (a lithium battery, a liquid). Price is only compared between services that could all carry this parcel and all keep the promise, which is why the filter runs first and writes its reasons down.

flowchart TD
  M[Measured parcel] --> R[Rate request per carrier]
  R --> Q[Quote rows]
  Q --> P[Promise filter]
  P --> L[Limits filter]
  L --> K[Rank on billed cost]:::accent
  K --> C[Chosen quote id]
  C --> B[Label purchase]
  P -->|none left| H[Hold for ops]
  L -->|none left| H

For a service that is not guaranteed, compare its estimate against the day before promised_by, since the estimate is a typical transit, not a commitment; a guaranteed service may use the date itself. Write the first failing check onto the quote as excluded_reason: late, over_weight, over_size, no_service or contents. When nothing survives, do not fall through to the cheapest service and hope. Write a hold on the shipment with the reasons from every quote, so ops can split the parcel, or agree a later date with the customer and re-run the pipeline with the new promised_by.

You know this worked when no chosen quote on any shipment has an estimate later than its order's promised_by.

Rank the survivors on billed cost, not the headline rate

The headline rate leaves out the surcharges the carrier already knows at quote time: residential delivery, a remote destination, fuel, an oversize box. Rate responses return these as separate lines, and the economy service that wins on base rate loses once a remote area surcharge lands on it. Billed cost is the base plus every surcharge line plus anything you must buy to use the service, such as a pickup fee for a service with no drop-off near the warehouse.

// Simplified: filter with a reason, then rank on billed cost.
type Surcharge = { code: string; amountMinor: number };

type Quote = {
  quoteId: string;
  baseMinor: number;
  surcharges: Surcharge[];
  estimatedDelivery: string; // ISO date, compares as text
  guaranteed: boolean;
  billableWeightG: number;
};

type Limits = { maxWeightG: number; maxLengthMm: number };

function exclude(q: Quote, s: Limits, promisedBy: string, lengthMm: number) {
  const latest = q.guaranteed ? promisedBy : dayBefore(promisedBy);
  if (q.estimatedDelivery > latest) return 'late';
  if (q.billableWeightG > s.maxWeightG) return 'over_weight';
  if (lengthMm > s.maxLengthMm) return 'over_size';
  return null;
}

function billedCost(q: Quote): number {
  return q.baseMinor + q.surcharges.reduce((t, s) => t + s.amountMinor, 0);
}

function rank(survivors: Quote[]): Quote[] {
  return [...survivors].sort(
    (a, b) =>
      billedCost(a) - billedCost(b) ||
      a.estimatedDelivery.localeCompare(b.estimatedDelivery),
  );
}

Break a tie on the earlier estimate, and after that on a per-lane carrier weight that ops set and can change without a deploy. Price decides between two survivors however far apart their estimates are, since both already passed the promise filter; the estimate only separates two services that bill the same amount. You know this worked when the chosen quote's billed cost equals the amount the label call charges on most shipments, and the difference is a named surcharge on the rest.

Buy the label against the quote id, and re-shop when it has expired

The label call must send the same parcel and the same service the quote was for, which is why the shipment stores chosen_quote_id and the label call takes that id and nothing else. I have integrated DHL, FedEx, UPS and USPS behind one cross-border procurement flow, and the rule I apply is that a label is never bought by service name. A quote has an expires_at; a label bought after it is bought on a price the carrier no longer offers.

Walk through the failure. The parcel is quoted on 22 October at 14:00 and the chosen quote expires at 23:59. Packing runs late, and the label job buys the label on 23 October at 09:10 with the service name copied from the quote. The carrier's surcharge table changed overnight, and the label response carries a charge of 5,840 cents against a quote of 5,610. The ledger expected 5,610, the customer sees nothing, and the carrier invoice three weeks later shows 5,840; reconciliation opens an exception on a shipment that is long delivered, and nobody can say whether the economy service would now have won.

With the id in the call, the label job reads the quote, sees expires_at in the past, and refuses. It re-runs steps two to four on the same measured parcel, stores the new chosen_quote_id on the shipment, and only then buys the label. When the quote is live and the label still charges a different amount, write label_variance_minor on the shipment, accept it below a tolerance set per carrier (50 cents as a starting example) and open a review above it; never void a label over a variance. You know this worked when no label on any shipment references a quote whose expires_at is earlier than the label's bought_at.

Match the invoice line to the quote and feed every adjustment back

The carrier invoice is the final price, and it arrives as lines keyed by tracking number, with adjustments (a re-weigh, an address correction, a remote area reclassification) as separate lines carrying the carrier's adjustment code. Matching the invoice to the quote closes the loop that the first five steps opened: it tells you which carrier's quotes hold and which carrier's quotes are optimistic on which lane.

flowchart TD
  I[Invoice line] --> T[Match on tracking number]
  T --> S[Shipment and chosen quote]
  S --> D{Within tolerance}
  D -->|yes| E[Post as expected cost]
  D -->|no| V[Variance with carrier code]:::accent
  V --> W[Adjustment share per lane]
  W --> X[Check the dimensioner]
  W --> Y[Refresh divisor table version]
  T -->|no match| U[Unmatched queue]

Match on tracking number to the shipment, then through chosen_quote_id to the quote, and compare the invoice total for that tracking number against billed_cost_minor. Inside the tolerance it posts as the expected cost; outside it, write a variance row with the carrier's adjustment code, and for a re-weigh store the carrier's billed weight next to your billable_weight_g. Then aggregate variances by carrier, lane and month. A rising share of re-weigh adjustments on one carrier means that carrier's divisor table is stale; a rising share across every carrier means the dimensioner is drifting. Either way the fix is an input to step one.

You know this worked when every invoice line either matches a shipment's quote within tolerance or sits in a named variance, and the unmatched queue is empty at month end.

Build the quote table first and make the label call take a quote id, because every other step either writes to that table or reads from it. Then put the measured_at gate on the rate request, and only after that spend time on the ranking.