GuidesTracking a shipment

Getting tracking information

Read a shipment's status and tracking events, and know when to check again.

1 min read

Tracking information for a shipment is available among the details exposed by the Retrieve a shipment endpoint.

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

curl --request GET \
  --url https://sandbox.api.mothership.com/beta/shipments/MS5016101 \
  --header "Authorization: Bearer $MOTHERSHIP_API_TOKEN" \
  --header 'Accept: application/json'

{
  "data": {
    "id": "MS5016101",
    "createdAt": "2019-03-19T17:03:24.542Z",
    "trackingUrl": "https://dashboard.mothership.com/track/MS5016101",
    "price": 79,
    "earliestPickupDate": "2019-03-19T17:15:55.000Z",
    "estimatedDeliveryDate": "2019-03-20T05:00:55.000Z",
    "status": "Unallocated",
    "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",
      "timezone": "America/Los_Angeles",
      "accessorials": ["liftgate"],
      "phoneNumber": "+15555555555",
      "openTime": "1000",
      "closeTime": "2200",
      "emails": ["logistics@mothership.com"]
    },
    "delivery": {
      "placeId": "ChIJsXqcyjy5woARNz6sOh0ZmwA",
      "name": "LACMA",
      "street": "5905 Wilshire Boulevard",
      "city": "Los Angeles",
      "state": "CA",
      "zip": "90036",
      "timezone": "America/Los_Angeles",
      "accessorials": ["liftgate", "residential"],
      "phoneNumber": "+15555555555",
      "openTime": "1100",
      "closeTime": "1700",
      "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.
trackingUrl	A page where anyone with the link can follow the shipment.
estimatedLocation	Estimated current `latitude` and `longitude` of the shipment, when one is available. It is often absent, so don't depend on it.

Tracking events

For the history of a shipment rather than its current state, call Track a shipment. It returns one event per update, with the carrier's PRO number once a carrier is assigned.

curl --request GET \
  --url https://sandbox.api.mothership.com/beta/tracking/MS5016101 \
  --header "Authorization: Bearer $MOTHERSHIP_API_TOKEN" \
  --header 'Accept: application/json'

{
  "data": {
    "results": [
      {
        "eventType": "shipmentBooked",
        "shipmentReferenceNumber": "MS5016101",
        "timestamp": "2019-03-19T17:03:24.542Z",
        "status": "Unallocated",
        "description": "Shipment booked and awaiting carrier assignment",
        "timezone": "America/Los_Angeles"
      },
      {
        "eventType": "statusUpdated",
        "shipmentReferenceNumber": "MS5016101",
        "proNumber": "1234567890",
        "timestamp": "2019-03-19T19:31:11.124Z",
        "status": "EnrouteToPickup",
        "description": "Carrier is en route to the pickup location",
        "city": "Los Angeles",
        "state": "CA",
        "pickupLocationName": "Griffith Observatory",
        "timezone": "America/Los_Angeles"
      }
    ]
  }
}

When to check for updates

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 Creating a webhook configuration for details about how to subscribe to shipment.status.updated events.