Shipping & dispatch

How Business Central feeds a carrier or route-planning system and takes its results back. Every flow here is a round trip. Business Central pushes the data, the external system does the physical work, and the result is written back afterwards. Nothing in this extension blocks the warehouse waiting for a carrier.

What this extension is, and what it is not

The integration is an asynchronous system of record. It is deliberately not a pack station and not a route planner:

Carrier and label systems (ShipStation, DPD, UPS, DHL, 3PLs) own packing, rating, label generation, printing and pickup booking.
Route planners (Stream, Descartes, Maxoptra) own route optimisation and the dispatch board.
Business Central owns the documents, the stock movement and the accounting, and stores what the external system sends back.

BC data ──push──▶ external system (does the work) ──writeback (async, after)──▶ BC

> [!IMPORTANT]

> When to use a dedicated shipping ISV instead. If you need a synchronous cartonize-and-print experience at a high-volume pack station (the operator scans a box, and a label prints in the same breath), this is the wrong tool. Use a dedicated shipping ISV (Dynamic Ship, nShift, ShipStation's own Business Central connector) for that station, and use these endpoints for the data layer around it. This is a deliberate boundary, not a missing feature. The endpoints here are built for volume that arrives in batches, not for a keystroke-latency loop.

Two entry paths, one writeback core

There is no single happy path. Which one you are on depends on whether Business Central runs the warehouse.

	Simple: no WMS	WMS: warehouse shipments
Who fulfils	The external tool ships it	Business Central picks, packs and posts
Upstream anchor	Sales Order	Warehouse Shipment
Trigger	order released	ready to ship (packed)
Posting	external reports shipped → `markShipped`	Business Central posts the warehouse shipment
Writeback lands on	Posted Sales Shipment	Posted Sales Shipment

Both paths converge on the posted sales shipment. That is where the tracking number and the label end up regardless of how the goods left the building, so a consumer reading shipment results only has to understand one shape.

Triggering the push

Simple flow. Subscribe a realtime trigger to salesOrders and filter for status eq 'Released'.

The subscriber owns fire-once. Business Central change tracking fires on every modify, not on the Open→Released transition, and with no previous value to compare against. A released order that is later edited notifies again. Your integration must remember which orders it has already pushed and skip repeats; a repeat means a second label, a second parcel, and a second carrier charge for the same order. There is deliberately no "sent to shipping" flag in Business Central to lean on.

WMS flow. Subscribe to warehouseShipments. Weight and parcel count are not known until the shipment is packed, so the ready-to-ship state is the meaningful trigger, not order release.

Recording the result

What came back	Where it goes
One tracking number for the whole shipment	`updateTracking` on the posted shipment, or `markShipped` on the order
The carrier label file	`documentAttachments` against the posted shipment
A freight charge to bill on	`addFreightCharge` on the order (inserts a real sales line)
Ordered drops for an own-fleet van	`routeStops`

One tracking number per shipment in this release. A shipment carries a single carrier tracking number, on the posted shipment header. Recording a shipment as several individually tracked boxes is not supported in the initial release. Where a carrier splits a shipment, write back the consignment-level tracking number and keep the per-box detail in the shipping system.

Own-fleet route dispatch

For a company running its own vans, a vehicle load is a warehouse document, with no separate "run" or "trip" entity. The route planner pushes its plan into Business Central with one call per van:

createDeliveryLoad on salesOrders assembles one warehouse shipment from several released orders (the bound order plus an additionalOrderNumbers list);
createPickupLoad on salesReturnOrders mirrors it inbound: one warehouse receipt from several return orders.

The route id lands on the document's integrationId, the vehicle on its shipping agent + service, the route date on its shipment/receipt date, and the ordered drops (or collections) are written back as routeStops, which the warehouse sees on the native Business Central pages as the loading sequence. Delivery and collection progress flows back by PATCHing each stop's status (Planned → Loaded → Delivered, or Collected for a pickup).

Weights, volumes and units

Every weight and dimension in these endpoints is a bare number with no unit attached. Business Central has no per-field unit of measure for mass or volume. The values are in whatever mass and length units the company is configured for. The integration map is responsible for translating them into what the carrier expects. Check the company's setup once, hard-code the mapping, and do not assume kilograms.

The same applies to the rollups (totalWeight, totalVolume on a warehouse shipment) and to the per-unit item values (grossWeight, netWeight, unitVolume). A line total is the per-unit value multiplied by the line quantity.

Returns

The inbound mirror uses the same building blocks. A Sales Return Order carries the return tracking and label, and Business Central's native RMA handles the receipt and credit memo. An own-van collection is a warehouse receipt with route stops, exactly mirroring a delivery.

What is out of scope

Carrier API calls · rate shopping · label rendering and printing · route optimisation · a dispatch board · a driver app or proof-of-delivery capture · a synchronous pack station · cartonization or per-box parcel records owned by Business Central · delivery-status tracking after the parcel leaves. Those belong to the carrier or planner you are integrating with.