Shipments
A shipment is a group of goods that move together from one address to another. It is the central record of Cargopilot. The quotations, the waybill, and the delivery plan all refer to a shipment.
A shipment usually comes from a sales order. Read Orders and shipments to split an order into shipments. You can also create a shipment directly, for example for a customer with no order in Miridia.
Create a shipment
Send POST /api/v1/shipments, or select New shipment in the portal. A shipment has these parts:
| Part | Content |
|---|---|
| Customer | The customer who receives the goods. |
| Handling type | Delivery or Collection. |
| Fulfilment type | Package, Pallet, Container, or Miscellaneous. |
| Collection | The collection date, the earliest and the latest collection date, the time window (collectAfterTime and collectBeforeTime), and remarks. |
| Delivery | The delivery date, the earliest and the latest delivery date, the time window (deliverAfterTime and deliverBeforeTime), and remarks. |
| Dimensions | The weight, the length, the width, and the height, with their units. You can use a dimension preset in place of the values. |
| Approval | Set requiresApproval to true if a person must approve the shipment first. |
Each shipment gets a code, for example for use on a label or in a conversation with a customer. When a shipment is created, Miridia raises the OnShipmentCreated event. A connected carrier then gets a request for a quotation. Read Carriers and quotations.
Times
Write a time in 24-hour format, for example 08:00 or 17:30. Write a date in ISO 8601 format.
Dimensions and presets
A carrier price depends on the size and the weight of the goods. Thus give the dimensions of each shipment.
A dimension preset is a package size that you use often, for example "Small box" or "Euro pallet". It holds the fulfilment type, the weight, the length, the width, the height, and the units. Make one preset the default. Send GET /api/dimensions/get-default-preset to read it. In the portal, manage the presets on the Fulfillment Presets page.
- The units of length are
Centimeter,Meter,Inch, andFoot. - The units of weight are
Gram,Kilogram,Tonne,Pound,Stone,UsTon, andImperialTon.
Miridia also gives preset templates for your country. Send GET /api/dimensions/templates to read them, and copy a template into your own presets.
Shipment status
The status shows where the goods are. The statuses follow the path of a shipment:
| Step | Statuses |
|---|---|
| Start | Active |
| Collection | PendingCollection, CollectionUnassigned, CollectionAssigned, CollectionRejected, CollectionException, CollectionFailedAttempt, Collected |
| Hub | AtHub, ReturnedToHub, InTransit, AtDestinationHub |
| Delivery | DeliveryUnassigned, DeliveryAssigned, DeliveryRejected, DeliveryException, OutForDelivery, DeliveryFailedAttempt, InLocker |
| End | Delivered, Cancelled |
A shipment does not have to pass through each status. For example, a shipment with your own vehicle can go from Active to OutForDelivery and then to Delivered.
To change the status, send PATCH /api/v1/shipments/{shipmentId} with the new status. The same request can also set the dateOfPickup, the dateOfDeparture, and the dateOfDelivery. The request changes only the fields that you send.
{
"status": "Delivered",
"dateOfDelivery": "2026-10-02T14:20:00Z"
}
Each change raises the OnShipmentStatusChanged event. The statuses Delivered and Cancelled also raise OnShipmentDelivered and OnShipmentCancelled. The status of the shipment also moves the status of its sales order. Read Orders and shipments.
The carrier of the shipment sends its status updates to Cargopilot, and Cargopilot sets the status. A person, a workflow, or an API client can also set the status.
Request a collection
When a carrier is assigned to a shipment, you can ask for a collection. Send POST /api/v1/shipments/{shipmentId}/collect with the dateOfCollection. Miridia raises the OnShipmentDeliveryRequested event. A workflow can then send the request to the carrier.
Waypoints
A waypoint is a stop between the origin and the destination, for example a hub or a cross-dock. Add a waypoint with POST /api/v1/shipments/{shipmentId}/waypoints, and give a Miridia location. Each waypoint records the time when the goods arrive (check-in) and leave (check-out).
Tracking number and barcode
Each shipment has a trackingId and a barcode. Use trackingId for the tracking number of the carrier. For the shipment document, read Waybills and labels.
History of a shipment
Keep all the data about a shipment on the shipment:
- Comments. Your team adds comments with
POST /api/v1/shipments/{shipmentId}/comments. Miridia records the author and the time. - Attachments. Add a file or a link, for example a photo of the goods or a signed delivery note. First upload the file with
POST /api/files/single. Then add it withPOST /api/v1/shipments/{shipmentId}/attachments. - Metadata. Add free key and value pairs with
POST /api/v1/shipments/{shipmentId}/metadata. A value ofnullremoves the key. - Traces. Miridia records each change to the shipment. Read the log with
GET /api/v1/shipments/{shipmentId}/traces.
Find shipments
GET /api/v1/shipments returns a page of shipments. Filter by status, customerId, and a date range with from and to. Use $search to find a code or a name. GET /api/v1/shipments/unassigned returns the shipments that are not in a delivery plan yet. GET /api/v1/shipments/overview returns the numbers for the shipment dashboard.
Service levels and fulfilment options
A shipment has a service level, for example Standard, Express, SameDay, Overnight, TwoDay, InternationalStandard, InternationalExpress, OnDemand, or Freight.
A service level template gives a service level your own name, price, time window, and description. An example is "Before 10:00, R 150". Manage the templates with /api/fulfillments/service-level-templates.
The fulfilment lookups list the sub-types of each fulfilment type, for example StandardEuroPallet or Reefer40Ft, and the delivery types, for example DoorToDoor or LockerToLocker. Read the Fulfilment reference.