Shipments

A shipment records the physical delivery of equipment against a purchase order. The Shipments area of the plugin tracks who is delivering each consignment, how much they are bringing, when it arrived, and how the items received reconcile against what was ordered.

Couriers and Accounts

A courier is any organisation that delivers equipment - a freight carrier, a parcel service, or even a vendor's own delivery van. Each courier has a name, an optional internal code, an optional tracking URL, and supports NetBox contact assignment.

The tracking URL is the most useful courier-level field. When set, every tracking number recorded on a shipment dispatched by that courier is rendered as a clickable link, with the tracking number appended to the URL. This turns a raw shipment record into a one-click jump to the courier's tracking site.

A courier account represents a specific account number you hold with a courier - useful when shipping costs are billed back to different cost centres or when separate accounts are used for inbound and outbound freight. Accounts are optional on a shipment but must belong to the shipment's courier when specified.

Shipments

A shipment records a single physical delivery against a purchase order. Each shipment captures:

• The purchase order being delivered.
• The courier delivering the consignment, plus an optional courier account.
• A tracking number, unique per courier.
• An optional destination site and location within that site.
• Optional date shipped, date expected, and date received values.
• A status describing where the shipment currently is in its journey.

A purchase order may have any number of shipments. This is the normal case for orders that arrive in multiple consignments, for replacements after damaged goods, or for orders that are dispatched in waves as items become available from the vendor.

Shipment Lifecycle

A shipment moves through one of these statuses:

• Prepared - the shipment is staged but has not yet left the vendor.
• Shipped - the consignment is in transit.
• Received - the consignment has arrived at its destination.
• Cancelled - the shipment was abandoned before being dispatched.
• Returned - the consignment was sent back to the vendor after delivery.
• Lost - the consignment was lost in transit and is not expected to arrive.

Which transitions between these statuses are permitted is governed by status transition rules.

Shipment Line Items

A shipment line item records that a specific BOM line item is included in a shipment, with:

• A quantity shipped - what the courier is carrying.
• An optional quantity received - what was actually unpacked at the destination.

Distinguishing shipped from received is important: a partial shortfall, a damaged unit, or a miscounted carton can all be recorded by setting the received quantity to less than the shipped quantity, leaving an audit trail of the discrepancy.

Receiving Equipment

Two object actions streamline the receiving workflow:

• Add to Shipment - from a purchase order's PO line items list, select the lines being delivered and add them to a shipment in bulk, specifying the shipped quantity for each.
• Mark Received - from a shipment's line items list, select the lines that have arrived and set the received quantity for each in bulk.

Together these turn a typical receiving session - "these ten cartons just landed at the loading dock; here's what's in each one" - into a few selections rather than a row-by-row edit.

Tracking Shipments

When a courier has a tracking URL configured, every tracking number recorded on a shipment is rendered as a clickable link that opens the courier's tracking site directly.

The shipment detail view also provides a Track button in the action toolbar that opens the tracking link in a new tab, and a copy-to-clipboard button next to the tracking number attribute for quick sharing.

Archiving

Shipments that have been received, returned, or cancelled can be archived to remove them from the default list view without deleting them or disturbing their data. Archiving is reversible: an archived shipment can be unarchived to resume editing.

While a shipment is archived it is read-only - it cannot be edited, have its status changed, or have its line items added, modified, or deleted. It can still be deleted while archived.

Archived shipments are hidden from the list view by default. Use the Archived filter to include them.

Closing the Loop Back to Designs

Each individual planned object on the originating BOM is recorded as an asset. The data model carries a link from each asset to the shipment that delivered the equipment for it, so that - once populated - you can trace each planned device, rack, module, or cable in NetBox back to the consignment it arrived on. The same record can alternately reference the spares pool it was drawn from, capturing the case where a requirement was fulfilled from existing inventory rather than from a new purchase.

The Install Workflow

When a planned rack, device, module, or cable in NetBox is covered by an asset that has not yet been installed, the plugin adds an Install button to that object's detail page. The button offers two ways to fulfil the requirement:

• Install from shipment - pick a shipment in received status (the form lists shipments associated with the same BOM), or
• Install from spares pool - draw from existing inventory; see Spares Management for details.

On submit, the underlying NetBox object is updated (status, serial number, asset tag, tags, and other attributes can be edited inline) and the asset is linked to the chosen shipment or spares pool - recording for posterity which delivery or pool fulfilled which requirement.

The Install button appears only on planned objects, and only while the asset is unfulfilled. Once installed, the button disappears.

The same action is available over the REST API by POSTing to /api/plugins/asset-lifecycle/assets/<id>/install/ with either a shipment or a spare_item ID in the body.