# Getting tracking information

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

Tracking information for a shipment is available among the details exposed by the [Retrieve a shipment](https://developers.mothership.com/reference/getshipmentdetails) endpoint.

Let's fetch these details using the shipment ID returned by the [Create a shipment](https://developers.mothership.com/reference/createshipment) endpoint, as in the request below.

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

```json 200 Response
{
  "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](https://developers.mothership.com/reference/shipment-status) 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](https://developers.mothership.com/reference/fetchshipmenttracking). It returns one event per update, with the carrier's PRO number once a carrier is assigned.

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

```json 200 Response
{
  "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](https://developers.mothership.com/reference/webhooks#shipment-status-updated-event) webhook event that fires each time a significant status update occurs.

See [Creating a webhook configuration](https://developers.mothership.com/docs/webhook-create) for details about how to subscribe to `shipment.status.updated` events.

> [!NOTE]
> For shipment tracking, we recommend polling Retrieve a shipment no more than once every 5 minutes, or relying on the [shipment.status.updated](https://developers.mothership.com/reference/webhooks#shipment-status-updated-event) webhook event to indicate when Retrieve a shipment should be called.