Rates And Surcharges
Published
A shipping quote is four or five numbers multiplied together, and every one of them arrived from a commercial negotiation. This pass protected a file that configures a rate engine, renamed its property names a group at a time, and read the quoted price off the far side. Every arm still produced a price. None of them threw. One of them charged a customer forty-five percent more for the same box.
The quote, and the five things deciding it
The sample is an ordinary rate card. A dimensional divisor of 250 is configured, which is better than the industry default of 166 and is the whole reason the carrier agreement was signed. Dimensional weight is switched on. A surcharge ceiling of twelve percent caps the fuel and residential stack that would otherwise reach 25.5 percent. Two service levels are sellable and the rest are not. A callback applies the customer's negotiated discount, and the currency is pinned to the value the engine already uses so it can serve as a control.
The parcel that matters is six pounds of foam in a box measuring thirty by twenty-four by twenty inches. Unprotected, the engine computes 14,400 cubic inches over the negotiated divisor of 250, bills it as fifty-eight pounds, applies the capped twelve percent surcharge and the thirty-two percent volume discount, and quotes 68.31 dollars. Every figure in this article is one a protected sample printed.
Five separate options contributed to that number. They were configured at different times by different people, and only one of them reads like a price.
The divisor, and a forty-five percent overcharge
Renaming dimFactorCuIn alone reverts the divisor from 250 to the library default of 166. The configuration line says so plainly -- dim-divisor=166 -- but nothing downstream complains, because 166 is a perfectly ordinary divisor. The same box is now billed as eighty-seven pounds instead of fifty-eight, and the quote rises from 68.31 to 99.24 dollars.
That is a thirty-dollar difference on one parcel, produced by a value reverting to a number that is not wrong in general, only wrong for this account. It is the shape that makes rate bugs so durable: the output is plausible, internally consistent, and reproducible. A merchant who checks the arithmetic will find it correct. The divisor is the input nobody re-derives.
The dense forty-four pound box in the same run barely moved: its dimensional weight went from four pounds to six, and since both are below its actual weight the quote stayed at 53.39 dollars. A test suite built around a normal parcel would pass. The overcharge lives entirely in light bulky freight, which is exactly the traffic a negotiated divisor exists to price.
The inert half that made a pair look safe
Dimensional weight is switched on by a second option sitting on the same object, dimWeightEnabled. Renaming it produced no change whatsoever, on either target. That is not luck and it was predicted before the arm ran: the value configured is true, and the library's default is also true, so losing the name reverts it to the value it already had.
Renaming both names together is therefore byte-identical to renaming the divisor alone -- the same eighty-seven pound bill, the same 99.24 dollar quote. A reviewer looking at the combined result and then at the two halves would see one half doing all the damage and conclude the other half is harmless. It is harmless here, for one reason that has nothing to do with what it controls: somebody happened to configure it to the vendor's default.
This is worth separating from the general case. An option whose configured value equals the vendor default is genuinely inert under renaming, and it is the only category that reliably is. The moment somebody switches dimensional weight off to model a flat-rate contract, that same rename starts silently switching it back on.
The ceiling, and the allowlist
Renaming maxSurchargePct removes the twelve percent ceiling and reverts it to the library default of none. The 25.5 percent fuel and residential stack now passes through in full: the bulky parcel goes from 68.31 to 76.55 dollars and the small ground parcel from 11.66 to 13.07. The acceptance line stops printing [capped], which is the only trace, and it is a trace nobody reads on a successful quote.
Renaming allowedServices removes the list of service levels the account may sell. Overnight, which the unprotected engine refuses with service-not-on-allowlist(overnight), is quoted at 45.32 dollars. A customer can now buy a service the account has no contract for, at a price the rate card was never meant to produce.
Renaming service -- the field on the service record rather than the option holding the list -- does the opposite. Every quote in the file is refused with service-not-on-allowlist(undefined), including the ones that should succeed. The same allowlist, reached two different ways: losing the option that carries it admits everything, and losing the value it matches against refuses everything. Only the second failure tells you it happened.
The negotiated agreement, and the guard that hid its own loss
Renaming negotiatedRates does not switch the discount off. It replaces the customer's agreement with the library's built-in, which applies list rates. The configuration line changes from caller-supplied(applies the customer agreement) to library-builtin(list rates only), the thirty-two percent discount becomes zero, and the bulky parcel is quoted at 100.46 dollars instead of 68.31. The function is still present in the file and still correct. It is simply never called.
Renaming discountPct, the single field the callback returns its answer in, is the quieter version. The callback runs, computes thirty-two percent correctly, and hands back an object the engine reads the wrong key from. The quote is again 100.46 dollars. What makes this one instructive is a defensive line I had written in the engine: it coerces a missing discount to zero rather than letting it poison the arithmetic. That guard worked, and in working it converted a loud NaN into a quiet full-price quote. The only evidence is the acceptance line, which prints disc=undefined%.
Two neighbouring fields show what that guard was protecting against. Renaming pct on the surcharge rows, or weightLb on the parcel, produces total=NaN. Nothing renders, somebody notices within minutes, and the build is reverted. The arms that quietly charged full price are the ones that would have shipped.
What protection alone did, and what to do about it
Nothing. The file was protected on five profiles -- the ES5 default, the modern target, both emit-gate configurations and the string-encoding profile -- and produced byte-identical output on all five. Every quote matched to the cent. Renaming identifiers and encoding strings does not disturb a rate engine.
Every result above required member renaming, which is off by default and needs a regular expression naming the members it may rewrite. Keep that pattern anchored to names your own code owns on both sides. A rate card is the opposite of that: your file writes the keys and an installed engine reads them, so every key on the options object is a contract, and so is every field on the parcel and service rows you hand it.
Then add the assertion no rename can satisfy by accident. Take one light bulky parcel with a known answer -- six pounds in 14,400 cubic inches, billed at fifty-eight pounds, quoted at 68.31 dollars -- and assert the billable weight, the surcharge percentage, the discount and the total, each as an exact value. Every result in this article would have failed that assertion on the first build, including the two that quietly charged list price.
Frequently asked questions
Does obfuscating a checkout bundle change shipping prices?
Not by itself. The sample was protected on five profiles including the ES5 default, the modern target and string encoding, and produced identical quotes on all five. Every result in this article required member renaming, which is off unless you enable it and supply a pattern.
What happened when the dimensional divisor was renamed?
It reverted to the industry default of 166 from the negotiated 250. A six-pound box in 14,400 cubic inches was billed as eighty-seven pounds instead of fifty-eight, and the quote rose from 68.31 to 99.24 dollars. A dense parcel in the same run barely moved, so a test built on a normal box would pass.
Why did renaming two options do no more damage than renaming one?
Because one of them was configured to the same value the library defaults to. Losing that name reverted it to the value it already had, so the pair was byte-identical to the other half alone. That is the only category of option that is reliably inert under renaming, and it stops being inert the moment somebody changes the value.
Can renaming make a rate engine refuse every quote?
Yes, and that is the better outcome. Renaming the service field, rather than the option holding the list of sellable services, refused every quote with service-not-on-allowlist(undefined). Losing the option instead admitted a service the account cannot sell, at 45.32 dollars.
What does renaming a caller-supplied discount callback actually do?
It does not disable the discount. The library substitutes its own built-in, which applies list rates, so the quote rose from 68.31 to 100.46 dollars while the customer's discount function sat in the file, correct and never called. The configuration line reported the built-in, which is the only place it showed.
Why is a NaN quote one of the safer results?
Because it stops the checkout. Renaming the surcharge percentage or the parcel weight produced total=NaN, which nobody ships. The arms that produced a plausible full-price quote are the ones that reach production.
What single test would have caught all of these?
One light bulky parcel with a known answer, asserted exactly: the billable weight, the surcharge percentage, the discount percentage and the total. Asserting only that a price was produced, or that it was greater than zero, passes in every arm above.
Related reading