Basics of calculating package size

The shopping cart package size calculation estimates the length, width, and height of one package needed. The estimate can be used in shipping method dimension limits, shipping cost calculations, and information passed to shipping integrations. The result is calculated from the current products, quantities, and dimensions in the shopping cart, so the quality of the product information determines the usefulness of the estimate.

Package size calculation produces one package estimate

The cart package size calculation produces length , width , and height fields, as well as the maximum dimension max . The calculation models a single package, not the final number of shipments or packages. The result is an estimate that can be used by shipping methods and integrations, but it does not replace the actual packaging decision of the warehouse for irregular, fragile, or individually packaged products.

Adding, removing, or changing the quantity to a cart updates the total and package size of the cart. The API returns the calculation in the cart total.size data, so your integration partner or support can check the values in the JSON response. For example, the UI might show an estimate of 62 × 62 × 51 if the surface in question is implemented to use these fields.

The calculation first uses the packaging dimensions

The packaging size calculation primarily uses the product's packingSize value for each shopping cart line, and in its absence, the product's physical size value. This means that the Packaging Length (mm) , Packaging Width (mm) , and Packaging Height (mm) fields override the product's corresponding Length, Width, and Height fields when packaging dimensions are available.

If the product is shipped in a box, roll, or protective packaging, fill in the actual external dimensions of the sales package. Product dimensions alone may give an underestimate. If packaging dimensions are not available, fill in at least all three physical dimensions of the product; a missing, zero, or incorrect dimension will prevent accurate packaging of that row and will pass the entire basket to the estimation model.

Maintain dimensions on the product card in the Dashboard

The shipping dimensions of the product can be found in the Dimensions and Weights section of the Shipping tab of the product card in the Control Panel. Open Products at /products , select the product, and open Shipping . Enter the length, width, and height of the product and packaging in millimeters. Changes to the fields are saved automatically.

The UI unit for product dimension fields is millimeters. The packaging algorithm handles boxes in millimeters and divides the final dimensions by ten to return values from the shopping cart, so total.size values are centimeters. For example, 62 mm and 62 cm are not the same input: the field value for a 62 cm package is 620 mm.

The algorithm tries positions, rows and layers

The packaging algorithm creates a box from each product unit and tries different arrangements of its length, width and height. There are a maximum of 6 possible positions for the three different dimensions. The boxes are arranged from left to right in rows, rows in depth in layers and layers on top of each other. The best position is selected for each box based on the score.

The system arranges the boxes using four different heuristics, performs a layered packing for each arrangement, and selects the best-scoring result. This is a greedy estimate of one package, not a mathematical guarantee of perfect minimum packing. The same packing algorithm also applies to baskets of more than 50 product units; the implementation does not have a 50-unit swap limit for another model.

The evaluation model handles missing or incorrect dimensions

The package size estimation model is used if the product units cannot be formed into valid boxes or the packaging algorithm does not return a result. The reason may be a missing product identifier, missing length, width or height, or a zero or negative dimension. The model selection is not based on whether the shopping cart contains up to or more than 50 items.

The evaluation model compares two sizes. The base size takes the largest value of each ordered dimension from the products. The volume-based size calculates the cube root of the total volume of all products and quantities. The larger of the base size and the corresponding volume-based size is chosen for each final dimension, which is intended to avoid a result that is too small.

API reports the calculation result and basis

total.size response from the packing size calculation API includes the length, width, height, largest dimension, input hash, and the fields calcSource , calcReason , and cacheHit . calcSource is packed when the layer packing was successful, and estimated when the estimation model was used. calcReason indicates, for example, successful packing, cached plan, missing boxes, or empty packer result.

The session's cartPackingSize is not an optional boolean for packing size. It stores the cart hash and any packing plan to speed up the calculation. The cache is only used if the current cart hash matches; otherwise, the packing is recalculated. In your troubleshooting, check the API response total.size , its calcSource , and calcReason .

Test realistic packaging size

The package size test starts with a typical shopping cart of 1-5 items, with the actual packaging known. Check the dimensions and calcSource in the API response, and compare the result to the physical package. Then test with a larger number of items, but don't expect the model to change at 50 items. Also measure the response of the calculation in your own environment, as execution times of 2 milliseconds or microseconds are not guaranteed limits for the product.

If the result is too small or large, check the packaging dimensions, product dimensions, millimeter unit, and quantity for each row. estimated usually indicates that at least one row could not be packed accurately. Once the first correct shipments have been packed, compare the estimate with the actual dimensions. A recurring deviation is primarily corrected in the product packaging dimensions, rather than by hardcoding a single cart-specific result.

Leverage the assessment in delivery methods and integrations

The package size calculation estimate is suitable for checking the allowed dimensions of a delivery method, calculating the delivery price based on dimensions or volume, and enriching the shipment template to be forwarded to the carrier. For example, a delivery method can be excluded when the maximum length of the package exceeds 175 cm, if the specific rule of that delivery method uses this limit.

The integration must read the cart's recent total.size and consider whether the result packed or estimated . When pricing with tight dimensional limits or volumetric weight, the estimate result should be treated with caution. If the order may require multiple packages, special packaging, or splitting into shipments, a single package estimate alone is not sufficient for final shipping instructions.