Skip to main content

​
Overview

A wholesale order does not leave the warehouse as parcels. It leaves as cartons, a pallet, or a container, and for international freight the price is quoted by a forwarder after someone looks at the order — not by an API at checkout. Four pieces make that work, and none of them disturb retail shipping: One catalog serves both audiences. The same product ships parcel to a shopper and carton to a trade buyer, because freight methods sit on the ordinary shipping profile and are gated by who is buying rather than by what is bought. See delivery setup for profiles, zones and methods, and package types for the packaging vocabulary this builds on.

​
How products pack

Freight numbers are not derivable from retail shipping data. A case of 48 bottles is one carton, not 48 parcels — so a product says how its units pack, and the rest follows the chain unit → carton → pallet → cubic meters and weight. The geometry lives on a shared carton, because merchants reuse a handful of standard sizes across hundreds of products and one edit should fix all of them. What varies per product stays on the product:
Stored quantities are always units, at every level. purchase_unit only changes the vocabulary a storefront presents — a buyer shown “2 cartons” is buying 96 units. Two data errors are refused while the merchant is still editing rather than discovered through a customer complaint: an order_multiple that straddles carton boundaries can never ship whole, and quoting in cartons without saying how many units one holds leaves a storefront no way to render the offer. Reading a product back adds units_per_pallet, derived from the two divisors so a merchant sees the far end of the chain without doing the arithmetic. It is null unless both halves are recorded.
A product may only be packed into a package type of kind carton, and a carton with products packed into it cannot later become a pallet. Repack the products first.

​
The freight summary

The freight summary is the load as a forwarder reads it: how many units, the cartons they fill, the pallets those stack onto, the cubic meters they occupy and what the whole thing weighs.
total_volume is cubic meters and total_weight is kilograms, both as decimal strings. total_pallets is null unless every carton-bearing line says how it stacks — one silent product would understate the load, so no figure is better than a wrong one. complete is the field to read before quoting from any of it. False means part of the catalog carries no carton data, so those products were measured loose from their unit dimensions instead. The numbers are still the best available and real enough to quote against, but they are a floor rather than a total, and a surface using them should say so. A cart of unmeasured goods has no freight summary at all rather than one full of zeros, which would read as a shipment that takes up no space.

​
Where it appears

The per-product breakdown is back-office only. A buyer is told what their shipment costs and how big it is; which SKU accounts for which part of it is the warehouse’s business. Each admin line carries variant_id, sku, name, units, cartons, pallets, units_per_carton, cartons_per_pallet, weight_per_carton, volume, weight and its own complete flag.
A placed order’s summary is never re-derived from the live catalog. The freight provider freezes a copy onto the rate it quoted, and the order reads that — so a carton size corrected next month does not rewrite what this container held. Two freight consignments on one order are merged into the one load the forwarder sees, and a canceled one is left out.

​
Freight rates

A freight method is an ordinary delivery method priced by the Freight rate provider. That provider quotes nothing and says so: it returns a rate with no price, carrying the freight summary the merchant will send to the forwarder in place of an amount. Such a rate comes back with unpriced: true, and every money field on it reads “Quoted after review” rather than a figure. That matters: a zero cost rendering as “Free” over a container of goods is a promise the merchant cannot keep. Unpriced rates are also sorted after every priced one and are never preselected, so a buyer with a real parcel option still sees it first.
Checkout completes on an unpriced rate. The shipping price arrives afterwards, once the forwarder has quoted it.
How a wholesale buyer pays — deposits, net terms, credit limits — is a separate subject and is not part of freight in 6.0. Partial payments are generally available and predate this work. See payments.

​
Shipment tiers

Which freight method a load qualifies for is configuration, not code. Each tier — “Cartons”, “Pallet”, “20ft container” — is an ordinary delivery method bounded by a rule. Volume rule. Bounds the method by packed volume in cubic meters: a pallet method takes 1–15 CBM, a 20ft container 15–33, and the estimator offers whichever one the order actually fills. Its minimum is deliberately forgiving. A partly measured catalog understates the load, so the figure is a floor rather than a measurement — it may raise a shipment into a tier but never exclude it from one. A maximum still applies, since passing one on too small a number errs toward offering the method. Company rule. Splits freight from parcel by who is buying. On, the method is offered only to orders placed for a company, so a carton tier disappears from retail carts. Off, only to orders that are not, which keeps parcel methods away from wholesale buyers. A method with no company rule is offered to both, so the rule is only ever added to state a split.
A freight method never consults a calculator — there is no price to work out — so admin surfaces hide its pricing form. GET /api/v3/admin/delivery_methods/rate_providers lists the providers installed on the store, which is what a picker should read rather than a hardcoded list.