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

# Get Shipment

> Retrieve a shipment by its reference ID

Retrieve a single shipment by its reference ID. The endpoint always force-refreshes the shipment
from the logistics provider before returning, so the `status` and `status_updates` reflect the
provider's latest known state.

## Request

### Path parameters

<ParamField path="id" type="string" required>
  Shipment reference ID (e.g., `P2604154821`).
</ParamField>

## Response

On success, the API returns `200 OK` with the shipment object.

<ResponseField name="id" type="string" required>
  Shipment reference identifier.
</ResponseField>

<ResponseField name="status" type="string" required>
  Shipment lifecycle status. One of `pending`, `in_transit`, `delivered`, `fault`, or `cancelled`.
</ResponseField>

<ResponseField name="logistics_provider" type="string" required>
  Logistics provider. One of `go`, `dhl`, or `tof`.
</ResponseField>

<ResponseField name="tracking_number" type="string">
  External tracking number from the logistics provider. May be `null`.
</ResponseField>

<ResponseField name="origin" type="object">
  Pickup address. May be `null`.

  <Expandable title="address object">
    <ResponseField name="name" type="string" required>Company or location name.</ResponseField>
    <ResponseField name="street" type="string" required>Street name.</ResponseField>
    <ResponseField name="house_number" type="string" required>House number.</ResponseField>
    <ResponseField name="postal_code" type="string" required>Postal/ZIP code.</ResponseField>
    <ResponseField name="city" type="string" required>City.</ResponseField>
    <ResponseField name="country" type="string" required>ISO 3166-1 alpha-2 country code.</ResponseField>
    <ResponseField name="phone" type="string">Contact phone number. May be `null`.</ResponseField>
    <ResponseField name="email" type="string">Contact email. May be `null`.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="destination" type="object">
  Delivery address. Same structure as `origin`. May be `null`.
</ResponseField>

<ResponseField name="pickup" type="object">
  Scheduled pickup window. May be `null`.

  <Expandable title="pickup object">
    <ResponseField name="from" type="string" required>Start of pickup window as a UTC instant (ISO 8601 with `Z` suffix).</ResponseField>
    <ResponseField name="till" type="string" required>End of pickup window as a UTC instant (ISO 8601 with `Z` suffix).</ResponseField>
    <ResponseField name="timezone" type="string" required>IANA timezone of the pickup location (e.g., `Europe/Berlin`). Use to render `from` / `till` in pickup-location wall-clock.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="notes" type="string">
  Optional notes. May be `null`.
</ResponseField>

<ResponseField name="status_updates" type="object[]" required>
  Chronological lifecycle events from the logistics provider (oldest first). Each entry contains
  the raw provider-sourced status label and a timestamp. Empty array if the provider has not
  reported any events yet. Use this for debug / audit; rely on `status` for canonical current state.

  <Expandable title="status update fields">
    <ResponseField name="status" type="string" required>
      Provider-sourced status label (free-form text, e.g. `"Shipment picked up"`,
      `"Loading delivery trip"`, `"Delivered"`).
    </ResponseField>

    <ResponseField name="time" type="string" required>
      Time the event was observed (ISO 8601).
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="appointments" type="ShipmentAppointmentLink[]" required>
  Appointments linked to this shipment, oldest-link first. Empty array when no appointments are
  linked. Cross-reference each `id` against [Get
  Appointment](/api/appointments/get-appointment) for the full appointment payload.

  <Expandable title="Appointment link fields">
    <ResponseField name="id" type="string">
      Appointment UUID — cross-reference against
      [Get Appointment](/api/appointments/get-appointment).
    </ResponseField>

    <ResponseField name="added_at" type="string">
      ISO 8601 timestamp the appointment was first linked to this shipment.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="created_at" type="string" required>
  Creation timestamp (ISO 8601).
</ResponseField>

<ResponseField name="updated_at" type="string">
  Last update timestamp (ISO 8601). May be `null`.
</ResponseField>

## Error responses

| Status | Description                                                                                                     |
| ------ | --------------------------------------------------------------------------------------------------------------- |
| `400`  | Invalid ID format.                                                                                              |
| `403`  | Forbidden — your API key does not have access to this operation or the shipment is outside your access context. |
| `404`  | Shipment not found.                                                                                             |
| `500`  | Internal server error.                                                                                          |

<RequestExample>
  ```bash cURL theme={null}
  curl --request GET \
    --url https://anivahealth.com/api/v1/shipments/P2604154821 \
    --header 'x-api-key: YOUR_API_KEY'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "id": "P2604154821",
    "status": "in_transit",
    "logistics_provider": "go",
    "tracking_number": "GO123456789",
    "origin": {
      "name": "Aniva Berlin Mitte",
      "street": "Unter den Linden",
      "house_number": "42",
      "postal_code": "10117",
      "city": "Berlin",
      "country": "DE",
      "phone": "+4930987654321",
      "email": "berlin-mitte@anivahealth.com"
    },
    "destination": {
      "name": "LabClinic GmbH",
      "street": "Laborstraße",
      "house_number": "10",
      "postal_code": "80331",
      "city": "München",
      "country": "DE",
      "phone": null,
      "email": null
    },
    "pickup": {
      "from": "2026-04-15T07:00:00Z",
      "till": "2026-04-15T10:00:00Z",
      "timezone": "Europe/Berlin"
    },
    "notes": null,
    "status_updates": [
      { "status": "Shipment picked up", "time": "2026-04-15T09:42:00Z" },
      { "status": "Receiving station", "time": "2026-04-15T11:18:00Z" }
    ],
    "appointments": [
      {
        "id": "c9f3e2a1-7d6b-4c5e-b3a2-1f0e9d8c7b6a",
        "added_at": "2026-04-15T08:30:00Z"
      }
    ],
    "created_at": "2026-04-03T14:30:00Z",
    "updated_at": "2026-04-15T11:20:00Z"
  }
  ```

  ```json 404 theme={null}
  {
    "error": "Shipment not found"
  }
  ```
</ResponseExample>