Retrieving Shipments

Listing Shipments

Use the List Shipments endpoint to list all shipments within an account. This endpoint is useful to help find a shipment you don't know the ID of, all shipments created within a certain date range, or to find shipments in a specific state (upcoming, active, completed).

View a Single Shipment

Use a shipment publicShipmentId to get the full details of a specific shipment via the Retrieve a Shipment endpoint. This endpoint is useful for making sure information is accurate for an upcoming for active shipment or to display within your own application.

{
    "shipmentId": "My Example Shipment",
    "publicShipmentId": "PUBLIC_SHIPMENT_ID",
    "deviceIds": [
        "000000000000000"
    ],
    "autoComplete": true,
    "shipmentLegs": [
        {
            "mode": "Road",
            "carrierId": null,
            "containerId": null,
            "airWaybill": null,
            "fromCoordinates": {
                "latitude": 42.3807959,
                "longitude": -71.0797724
            },
            "fromAddress": {
                "street": "56 Roland St Suite 100A",
                "sublocality": "",
                "locality": "Charlestown",
                "state": "Massachusetts",
                "postalCode": "02129",
                "country": "United States"
            },
            "toCoordinates": {
                "latitude": 42.3604065,
                "longitude": -71.0577624
            },
            "toAddress": {
                "street": "1 City Hall Square",
                "sublocality": "",
                "locality": "Boston",
                "state": "Massachusetts",
                "postalCode": "02201",
                "country": "United States"
            },
            "isActiveLegOfShipment": true,
            "orderNo": 1,
            "startDateTimeUtc": "2022-02-03T16:24:44Z",
            "completedDateTimeUtc": null,
            "arrivalDateTimeUtc": null,
            "departureDateTimeUtc": "2022-02-03T16:24:44Z",
            "legLabel": "My Custom Leg Name",
            "shipFromDate": "2022-02-04T11:00:00Z",
            "etaDate": "2022-02-05T13:00:00Z",
            "currentEtaUtc": "2022-02-03T17:52:05Z",
            "distanceLeftKm": 3.7,
            "alertPresetIds": [
                123456
            ]
        }
    ],
    "customFields": [
        {
            "key": "Purchase Order",
            "value": "PO 1234"
        }
    ],
    "autoCompleteHoursDelay": 24,
    "sharedUrl": null,
    "isShared": false,
    "isStarted": true,
    "isDeparted": false,
    "isCompleted": false
}

Updating Shipments

If the need arises to update your shipment, the Update a Shipment endpoint should be used. Common uses are to update the shipment name or to change the expected start/delivery dates.

You will have the ability to edit any field for upcoming shipments, any field except devices for active shipments, and you will be unable to edit a shipment once it has completed.