Get Tracking Updates

Get tracking information about an ocean shipment. A shipment must be created and added to Project44's network before we can return tracking information. If you have not done so, please Create a Shipment. Project44 offers four targeted endpoints for returning shipment tracking information. This allows you to fetch the specific information you need when you need it.

The /api/v4/shipments/{shipmentId}/eventhistory endpoint returns shipment events, or milestones.
The /api/v4/shipments/{shipmentId}/positionhistory endpoint returns shipment positions.
The /api/v4/shipments/{shipmentId}/tracking endpoint returns only route segment and stop information for a shipment.
The /api/v4/shipments/{shipmentId}/tracking/history endpoint returns all shipment tracking information including events, positions, and stops and route segments.

All 4 endpoints have the same requirements and workflow. The only difference is the information returned in the response. So we will only describe the workflow once for the 4th API endpoint, which returns all shipment tracking information.

Our Shipment Tracking APIs are designed to be used in an asynchronous manner. This means that a behavior or functionality may not be immediately available upon submission to our API because our system processes data asynchronously.

For more information about how to use the specific endpoints and features, please consult our user guide and API Reference documentation.

Get Full Tracking History

Get an Ocean shipment's full tracking history including route information and stops, states, events, and positions.

Requirements

Have the following information available:

Master Shipment ID (this is the id returned in the 200 OK response during shipment creation).

Workflow

Complete the following steps.

Prepare a GET request to /api/v4/shipments/{shipmentId}/tracking/history using the Master Shipment ID. For example, GET /api/v4/shipments/cfa01403-d76d-4e01-a551-17589083d7d7/tracking/history.
Send the request.

Expected System Response

You have successfully submitted the request when you receive a 200 OK response. Here is a sample of the response schema:

JSON

{
    "shipment":
    {
        "id": "cfa01403-d76d-4e01-a551-17589083d7d7",
        "identifiers":
        [
            {
                "type": "CONTAINER_ID",
                "value": "EISU9182565"
            },
            {
                "type": "BILL_OF_LADING",
                "value": "143266096175"
            },
            {
                "type": "CONTAINER_TYPE",
                "value": "45GP"
            },
            {
                "type": "CARRIER_SCAC",
                "value": "EVRG"
            }
        ],
        "shipmentShareLink": "https://na12.voc.project44.com/portal/v2/public/ma/tracking-details?shipmentShareToken=67920a2c-f549-4935-89f2-da2389bb3ed1",
        "createdDateTime": "2023-01-16T21:02:07+0000",
        "lastModifiedDateTime": "2023-01-24T12:20:20+0000",
        "routeInfo":
        {
            "stops":
            [
                {
                    "id": "f5d0d694-995f-307c-9e11-a42118f71d64",
                    "type": "PORT_OF_LOADING",
                    "location":
                    {
                        "id": "8ed11615-78f6-4c16-85d0-223b3c216e0f",
                        "name": "Ningbo",
                        "identifiers":
                        [
                            {
                                "type": "PORT_UN_LOCODE",
                                "value": "CNNGB"
                            }
                        ],
                        "address":
                        {
                            "city": "Ningbo",
                            "state": "Zhejiang",
                            "country": "CN"
                        },
                        "coordinates":
                        {
                            "latitude": 29.895426,
                            "longitude": 121.61865
                        },
                        "timeZone": "America/New_York"
                    }
                },
                {
                    "id": "aad8730c-3ecd-3a9b-8d67-a445488d9806",
                    "type": "PORT_OF_DISCHARGE",
                    "location":
                    {
                        "id": "8ed11615-78f6-4c16-85d0-223b3c216e0f",
                        "name": "Vancouver",
                        "identifiers":
                        [
                            {
                                "type": "PORT_UN_LOCODE",
                                "value": "CAVAN"
                            }
                        ],
                        "address":
                        {
                            "city": "Vancouver",
                            "state": "British Columbia",
                            "country": "CA"
                        },
                        "coordinates":
                        {
                            "latitude": 49.283333,
                            "longitude": -123.11667
                        },
                        "timeZone": "America/New_York"
                    }
                }
            ],
            "routeSegments":
            [
                {
                    "id": "7c30a1b3-047b-378b-a921-fac0145779d2",
                    "fromStopId": "f5d0d694-995f-307c-9e11-a42118f71d64",
                    "toStopId": "aad8730c-3ecd-3a9b-8d67-a445488d9806",
                    "transportationMode": "OCEAN",
                    "identifiers":
                    [
                        {
                            "type": "VOYAGE_NUMBER",
                            "value": "0404-160E"
                        },
                        {
                            "type": "VESSEL_NAME",
                            "value": "EVER EXCEL"
                        },
                        {
                            "type": "VESSEL_IMO",
                            "value": "9241322"
                        },
                        {
                            "type": "CARRIER_NAME",
                            "value": "Evergreen"
                        }
                    ]
                }
            ]
        },
        "relatedShipments":
        [
            {
                "id": "309ddd75-4f93-4649-a1c5-0a02bb95210d",
                "identifiers":
                [
                    {
                        "type": "BILL_OF_LADING",
                        "value": "143266096175"
                    },
                    {
                        "type": "CARRIER_SCAC",
                        "value": "EVRG"
                    }
                ],
                "shipmentShareLink": "https://na12.voc.project44.com/portal/v2/public/ma/tracking-details?shipmentShareToken=4c87e967-42df-4412-9108-c04914e972e4",
                "createdDateTime": "2023-01-16T20:59:12+0000",
                "lastModifiedDateTime": "2023-01-24T12:20:22+0000"
            }
        ]
    },
    "states":
    [
        {
            "type": "IN_TRANSIT",
            "startDateTime": "2023-01-05T04:00:00+0000",
            "endDateTime": "2023-01-10T04:00:00+0000",
            "stopId": "f5d0d694-995f-307c-9e11-a42118f71d64",
            "routeSegmentId": "0505b425-e1b7-362b-8f41-9e4fecfbc7e2"
        },
        {
            "type": "AT_STOP",
            "startDateTime": "2023-01-10T04:00:00+0000",
            "endDateTime": "2023-01-13T06:29:00+0000",
            "stopId": "f5d0d694-995f-307c-9e11-a42118f71d64"
        },
        {
            "type": "IN_TRANSIT",
            "startDateTime": "2023-01-13T06:29:00+0000",
            "stopId": "f5d0d694-995f-307c-9e11-a42118f71d64"
        }
    ],
    "events":
    [
        {
            "dateTime": "2025-06-11T14:18:00+0000",
            "receivedDateTime": "2025-07-22T12:34:00+0000",
            "id": "a1163a6a-f275-4763-85f3-b0abe64282a9",
            "type": "ARRIVAL_AT_STOP",
            "stopId": "1821c712-82cc-58a0-8084-c8939b89bf75",
            "routeSegmentId": "90a27afe-30e3-59fd-8460-3ba0ba7e0949",
            "estimateDateTime": "2025-08-24T17:00:01+0000",
            "estimateLastCalculatedDateTime": "2025-07-22T12:35:05+0000",
            "plannedDateTime": "2025-08-18T06:00:00+0900",
            "dateTimes":
            [
                {
                    "type": "PLANNED",
                    "dateTime": "2025-08-18T06:15:00+0900",
                    "lastModifiedDateTime": "2025-07-22T12:34:00+0000",
                    "source": "CARRIER",
                    "sourceIdentifiers":
                    [
                        {
                            "type": "BOOKING_NUMBER",
                            "value": "143266096175"
                        },
                        {
                            "type": "CARRIER_SCAC",
                            "value": "MSCU"
                        },
                        {
                            "type": "CONTAINER_ID",
                            "value": "EISU9182565"
                        }
                    ],
                    "selected": false,
                    "sequence": 1
                },
                {
                    "type": "ESTIMATE",
                    "dateTime": "2025-08-24T17:00:01+0000",
                    "lastModifiedDateTime": "2025-07-23T08:09:44+0000",
                    "source": "P44",
                    "sourceIdentifiers":
                    [
                        {
                            "type": "REFERENCE_NUMBER",
                            "value": "3"
                        }
                    ],
                    "selected": true,
                    "sequence": 1
                }
            ],
            "details":
            {
                "ocean":
                {
                    "code": "VESSEL_ARRIVAL_AT_PORT_OF_DISCHARGE"
                }
            }
        }
    ],
    "positions":
    [
        {
            "dateTime": "2025-05-17T12:51:00+0800",
            "receivedDateTime": "2025-06-05T12:20:48+0000",
            "routeSegmentId": "07151ef4-44b4-53d7-8723-6b0439d5cd4b",
            "latitude": 1.35,
            "longitude": 103.55
        }
    ]
}

This is an example of what could be returned in the response. Null fields will not show up in the response. Please refer to the reference data for more information on required and potential null fields.

The response returned here for the Full Tracking History is the same response returned with the webhook. For more information on setting up a webhook to receive Full Tracking History updates, see Webhooks.

Errors

If there was a problem with your request, you will receive one of the following error codes:

400 Invalid request
401 Invalid or missing credentials
403 User not authorized to perform this operation
404 Not Found

See Error Responses in the Appendix for more information on the meaning of these error codes.

Fields and Objects

The fields and objects returned in the response are explained in detail in our Shipment Schema documentation. Please refer to the Ocean Shipment Schema for more information.

Ocean Milestones

Most of the ocean shipments will have the following 8 milestones:

PICKED_UP_AT_ORIGIN
GATE_IN_FULL_AT_PORT_OF_LOADING
LOAD_ONTO_VESSEL_AT_PORT_OF_LOADING
VESSEL_DEPARTURE_FROM_PORT_OF_LOADING
VESSEL_ARRIVAL_AT_PORT_OF_DISCHARGE
DISCHARGE_FROM_VESSEL_AT_PORT_OF_DISCHARGE
GATE_OUT_FULL_AT_PORT_OF_DISCHARGE
GATE_IN_EMPTY_CONTAINER_AT_TERMINAL

If there are any transshipment ports, the following milestones will be present:

VESSEL_ARRIVAL_AT_TRANSSHIPMENT_PORT
DISCHARGE_FROM_VESSEL_AT_TRANSSHIPMENT_PORT
LOAD_ONTO_VESSEL_AT_TRANSSHIPMENT_PORT
VESSEL_DEPARTURE_FROM_TRANSSHIPMENT_PORT

If Project44 discovers additional milestones from the carrier connections, those will be included in the response.
For more information on the above milestones and other milestones, see the $.events schema guide.

Expected Stops & Route

The following are the major stops you can expect to see for ocean shipments:

PICKUP
ORIGIN
PORT_OF_LOADING
TRANSSHIPMENT_PORT (if any)
PORT_OF_DISCHARGE
DESTINATION For more information on the above stops and other stops, see the $.shipment.routeInfo.stops schema guide.

Expected Identifiers

The identifiers used during shipment creation will be available as part of response. Also, those identifiers that are discovered during shipment tracking will also be surfaced. More information on identifiers can be found in the $.shipment.identifiers guide.

After the shipment has been created, Project44 will discover related shipments and return their information in the relatedShipments array in the GET responses. Related shipments will not be identified immediately after creation, however. If you want to see the related shipments immediately after shipment creation, you will need to include the related shipment identifier information in the identifiers array of the shipment creation endpoint. Follow the steps in Create an ocean shipment with associated containers to see how this works.