Getting Tracking Information

Tracking information for a shipment is available among the details exposed by the Get Shipment Details endpoint.

Let's fetch these details using the Shipment ID returned by Create Shipment endpoint as in the request below.

curl --request GET \
     --url https://sandbox.api.mothership.com/beta/shipments/72I2W1 \
     --header 'Accept: application/json'

{
    "data": {
        "id": "72I2W1",
        "createdAt": "2019-03-19T17:03:24.542Z",
        "price": 79,
        "earliestPickupDate": "2019-03-19T17:15:55.000Z",
        "estimatedDeliveryDate": "2019-03-20T05:00:55.000Z",
        "status": "Unallocated",
        "estimatedLocation": {
            "latitude": 34.1184341,
            "longitude": -118.3003935
        },
        "freight": [
            {
                "quantity": 2,
                "type": "Pallet",
                "weight": 50,
                "length": 48,
                "width": 42,
                "height": 46,
                "description": "T-shirts"
            }
        ],
        "pickup": {
            "placeId": "ChIJywjU6WG_woAR3NrWwrEH_3M",
            "name": "Griffith Observatory",
            "street": "2800 East Observatory Road",
            "city": "Los Angeles",
            "state": "CA",
            "zip": "90027",
            "coordinates": {
                "latitude": 34.1184341,
                "longitude": -118.3003935
            },
            "accessorials": [
                "liftgate"
            ],
            "phoneNumber": "+15555555555",
            "openTime": "1000",
            "closeTime": "2200",
            "emails": [
                "[email protected]"
            ]
        },
        "delivery": {
            "placeId": "ChIJsXqcyjy5woARNz6sOh0ZmwA",
            "name": "LACMA",
            "street": "5905 Wilshire Boulevard",
            "city": "Los Angeles",
            "state": "CA",
            "zip": "90036",
            "coordinates": {
                "latitude": 34.0639323,
                "longitude": -118.3592293
            },
            "accessorials": [
                "liftgate",
                "residential"
            ],
            "phoneNumber": "+15555555555",
            "openTime": "1000",
            "closeTime": "2200",
            "emails": []
        }
    }
}

Within the response, we can see the following tracking information.

Property	Description
status	Current status of the shipment. Refer to Shipment Statuses for more information.
earliestPickupDate	ISO 8601 string representing the earliest pickup datetime. This is unlikely to change from the date given on purchase.
estimatedDeliveryDate	ISO 8601 string representing the estimated delivery datetime. This is unlikely to change from the date given on purchase.
estimatedLocation.latitude	Estimated current latitude of the shipment.
estimatedLocation.longitude	Estimated current longitude of the shipment.

We can know when to poll for the above tracking information by subscribing to the shipment.status.updated webhook event that fires each time a significant status update occurs.

See Configuring Webhooks for details about how to subscribe to shipment.status.updated events.

📘
For shipment tracking, we recommend polling Get Shipment Details no more than once every 5 minutes, or relying on the shipment.status.updated webhook event to indicate when Get Shipment Details should be called.

For shipment tracking, we recommend polling Get Shipment Details no more than once every 5 minutes, or relying on the shipment.status.updated webhook event to indicate when Get Shipment Details should be called.