Package Splitting and Scopes

Flex Shipping supports two calculation models and a configurable package-building logic. This is the key to predictable pricing when carts contain mixed, bulky, or quantity-heavy products.

Calculation scopes

Shipment scope

The full cart is evaluated as one shipment. A matching shipment-level rate is selected and priced once.

Package scope

The cart is split into packages first. Then each package is matched against package-scope rates and priced individually. The final shipping amount is the sum of all package prices.

How package building works

Package creation is driven by method configuration and product-level packing attributes.

Supported pack modes

normal: items are packed together according to your split strategy and package limits
always_single: each unit becomes its own package
separate_max_n: units are split into packages with a configurable max quantity per package

Supported split strategies

First Fit Decreasing (ffd)
weight_first
volume_first
custom (with configurable custom sort order)

Package limits

You can enforce:

max package weight
max package volume

If limits are set, package building respects both constraints. If no limits are set, normal-mode items can stay in a single aggregated package.

Missing attribute handling

Package logic depends on product data (weight, dimensions/volume, packing mode, optional separate-max quantity).
If values are missing, behavior is controlled by the method policy:

strict/block behavior: calculation is stopped
default-value behavior: configured fallback values are used

This allows either strict data quality enforcement or controlled fallback operation.

Important edge behavior

Parent/child quote item handling avoids double counting.
Fractional quantities are normalized for package math.
If a product uses special pack modes with fractional quantity, logic falls back to normal packing to prevent invalid package states.
If no valid package can be built, the method does not return a shipping price.

Pricing impact

Package scope changes the commercial outcome:

Shipment scope: one rate decision for the full cart.
Package scope: multiple rate decisions, one per package, then sum.

This is especially useful when one cart contains products that should not share the same transport cost model.

Recommended setup sequence

Set attribute mapping for weight/volume/packing mode.
Define split strategy and package limits.
Choose calculation scope per method (shipment or package).
Create matching rates for the selected scope.
Validate realistic carts with the simulator before go-live.

Typical scenarios

mixed carts with lightweight and bulky products
products that must ship separately
B2B orders where package composition drives transport pricing

Operational result

You get a shipping result that reflects real package structure, not only cart totals. This improves pricing fairness, reduces manual shipping corrections, and increases checkout consistency.