Exceptions and packages

Record problems during delivery and declare the physical packages that make up a shipment.

When to use

Use exceptions when a delivery hits trouble (address issue, refused, damaged). Use packages when one shipment is made of several parcels.

Permissions: logistics:write to raise or resolve an exception and to add packages; logistics:read to view packages.
No feature toggles apply.

Open the shipment (/logistics/shipments/[id]) and record the exception with its reason.

Once the issue is sorted, resolve the exception so the shipment can continue.

Add each package of the shipment, and update a package’s status as it moves.

Log milestones on the shipment so the tracking history stays complete.

Raise an exception instead of leaving the status unchanged; it keeps the history honest and feeds carrier analysis.
Driver device clocks can be wrong; event times are corrected, so rely on event order.
Declare packages before dispatch so the warehouse and driver agree on the count.