> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kasiye.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Update shipment status

> Advance delivery status along pending, awaiting pickup, in transit, and delivered.

Advance a shipment one step along the delivery path. You cannot skip statuses, go backwards, or set `cancelled` here — use [cancel](/api-reference/cancel-shipment) for that.

## Allowed transitions

| Current status    | Next status you can send |
| ----------------- | ------------------------ |
| `pending`         | `awaiting_pickup`        |
| `awaiting_pickup` | `in_transit`             |
| `in_transit`      | `delivered`              |
| `delivered`       | None                     |
| `cancelled`       | None                     |

<ParamField path="shipment" type="string" required>
  Shipment reference, for example `SHP-12345`.
</ParamField>

<ParamField body="status" type="string" required>
  The next delivery status. Must be the single allowed next value for the shipment's current status.
</ParamField>

<RequestExample>
  ```bash theme={null}
  curl -X PATCH https://api.kasiye.com/v1/shipments/SHP-12345/status \
    -H "Authorization: Bearer shp_your_key" \
    -H "Content-Type: application/json" \
    -d '{
      "status": "awaiting_pickup"
    }'
  ```
</RequestExample>

Returns `200` with the shipment wrapped in `data`.

A shipment that belongs to another workspace returns `404`.

An invalid jump (for example `pending` to `delivered`) returns `422`:

```json theme={null}
{
  "message": "This status change is not allowed for the shipment.",
  "errors": {
    "status": ["This status change is not allowed for the shipment."]
  }
}
```

<Note>
  Payment status is separate. Marking a shipment `awaiting_pickup` through this endpoint does not collect payment. Use it when your own process (or a rider) needs to move delivery state.
</Note>