Shipping rates and parcels

A method's price is tabulated top to bottom and then clamped, and the order is the contract: the base rate, then the per-item rate multiplied by the quantity in the parcel, then the per-kilogram rate, then the percentage of the parcel's item price, then the per-class figure once per distinct shipping class the parcel holds, then the minimum and last the maximum. Both clamps are inclusive at the boundary. Every intermediate is minor units, every rate that is not a whole number of minor units goes through exact rational arithmetic, and the result is rounded once at the end. min_total_cost_minor is the clamp and min_total is the free-shipping threshold. The two names are far apart on purpose.

A cost_expression on a method replaces the whole table above and leaves both clamps in force. Everything in an expression is minor units, so Woo's 10 + ( 2 * [qty] ) is written 1000 + ( 200 * [qty] ) here, and a negative result is floored at zero. The token list is closed: decimal literals, + - * /, brackets, [qty], [item_count], [cost], [weight] and [fee percent="N" min_fee="N" max_fee="N"]. There are no function names, no variables you can invent and no path from a character a merchant types to a PHP callable. Anything outside the list is refused where it is typed, with the offending token named, by POST /kahunacart/shipping/expressions/validate as the merchant writes it and again by the save. Division by zero evaluates to zero and is noted in the adjustment's audit trail rather than taking a checkout down. shipping.expressions.enabled: false refuses to save an expression and ignores any already stored.

PUT /kahunacart/shipping/methods/{id}/rates also carries the three-valued class policy. allow is the default and consults nothing. disallow takes the method off when the parcel holds a line of a named class, require takes it off unless the parcel holds one. A method removed by policy comes back present, disabled and naming the class, as class_disallowed or class_required. A policy naming no classes refuses nothing. The route writes only the fields it is handed, so a client that has never heard of percent_rate cannot clear one.

A shipping profile says which consignment a product belongs to, and an order is packed into one package per profile its lines mention. default and digital ship with the plugin, a product with no profile of its own falls back to digital when it is a download and default otherwise, and an existing store therefore packs every order into one parcel and is charged what it always was. Packages come out in profile position order, the order's shipping total is the sum of its packages, and a package whose profile does not ship gets no method and no cost and is still written down. There is no weight or dimension packing. Deleting the default or digital profile is refused, and so is deleting a profile a product still points at.

KahunaCart ships no carrier. GET /kahunacart/shipping/carriers lists the drivers an add-on has registered, and a stock install answers with none. A carrier never blocks a checkout: an excluded service, a decline, a timeout, a driver that failed and a store with shipping.carrier_rates.enabled: false all come back the same way, as the method present, disabled and carrying a reason code of carrier_excluded, calculator_declined or carrier_unavailable, with the nominated fallback method carrying the order. A quote is cached on a hash of the destination, the parcel contents, its weight, its declared value and the currency, for shipping.carrier_rates.cache_ttl seconds. Saving a method's rates clears the set, and POST /kahunacart/shipping/carriers/cache/clear is the button for the merchant whose account manager changed a rate card this morning.