# Shipment status updated

> Sent when a shipment's status changes.

`eventType` is `shipment.status.updated`.

The first event for a new shipment has `newShipmentStatus` set to `Unallocated` and no `previousShipmentStatus` key, so treat that key as optional.

A shipment can jump ahead, for example when its carrier doesn't report every status. You still get an event for each status along the way, sent in lifecycle order, each with the status before it. A jump from `DriverAllocated` to `EnrouteToDelivery` sends three events:

| `previousShipmentStatus` | `newShipmentStatus` |
| --- | --- |
| `DriverAllocated` | `EnrouteToPickup` |
| `EnrouteToPickup` | `ArrivedAtPickup` |
| `ArrivedAtPickup` | `EnrouteToDelivery` |

The added events start at `DriverAllocated` and never include `FindingDriver`. A jump from `Unallocated` to `EnrouteToPickup` sends `Unallocated` to `DriverAllocated`, then `DriverAllocated` to `EnrouteToPickup`. A move back to an earlier status, or to `Cancelled`, sends one event.

Events can arrive out of order when one is retried. The event carries no time, and a step back is a real change, so don't drop an event because its status ranks below the one you have. When the current status matters, call [Get shipment details](https://docs.mothership.com/reference/getshipmentdetails).

## Subscribing

Add `shipment.status.updated` to a configuration's `subscribedEvents`. It needs no extra permission.

## Event data

- `newShipmentStatus` (string): The shipment's status now. One of: `Unallocated`, `FindingDriver`, `DriverAllocated`, `EnrouteToPickup`, `ArrivedAtPickup`, `EnrouteToDelivery`, `ArrivedAtDelivery`, `Completed`, `Cancelled`.
- `previousShipmentStatus` (string, can be missing): The status before this change. Missing from the first event of a new shipment. One of: `Unallocated`, `FindingDriver`, `DriverAllocated`, `EnrouteToPickup`, `ArrivedAtPickup`, `EnrouteToDelivery`, `ArrivedAtDelivery`, `Completed`, `Cancelled`.
- `shipmentId` (string): The shipment's reference number, such as `MS123456`. Pass it to Get shipment details.

## Envelope

Mothership sends a `POST` with this JSON body. The envelope is the same on every event, and `data` holds the keys above.

- `eventType` (string): The event. Always `shipment.status.updated` here. Route on it, and answer `2xx` to types you don't handle.
- `sentAt` (string): When Mothership queued the event to send, as an ISO 8601 string in UTC. Every retry and resend carries the same value, so it does not say when this attempt went out.
- `deliveryAttempt` (integer): Which send of this event this is, starting at `1`. Resends from the dashboard count too.
- `pendingRetries` (integer): How many automatic attempts are left if this one fails. `0` on the last one.

## Example request

```json Example body
{
  "eventType": "shipment.status.updated",
  "data": {
    "newShipmentStatus": "ArrivedAtPickup",
    "previousShipmentStatus": "EnrouteToPickup",
    "shipmentId": "MS123456"
  },
  "sentAt": "2026-10-08T15:04:05.000Z",
  "deliveryAttempt": 1,
  "pendingRetries": 16
}
```