> ## 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.

# Cancel Shipment

> Cancel a shipment order

Cancel a shipment order. This calls the logistics provider API to cancel the order and updates the shipment status to `cancelled`.

<Warning>
  Shipments cannot be cancelled after pickup. Attempting to cancel a shipment that has already been
  picked up, delivered, or previously cancelled returns `409 Conflict`.
</Warning>

## 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 cancelled shipment object.

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

<ResponseField name="status" type="string" required>
  Shipment lifecycle status. Will be `cancelled` after a successful cancellation.
</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 (ISO 8601 with timezone offset).</ResponseField>
    <ResponseField name="till" type="string" required>End of pickup window (ISO 8601 with timezone offset).</ResponseField>
    <ResponseField name="timezone" type="string" required>IANA timezone of the pickup location (e.g., `Europe/Berlin`).</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 has a
  `status` (free-form provider-sourced label) and `time` (ISO 8601). Empty array if no events
  observed yet.
</ResponseField>

<ResponseField name="appointments" type="ShipmentAppointmentLink[]" required>
  Appointments that were linked to this shipment before cancellation. Each entry is
  `{ id, added_at }`; cross-reference each `id` against
  [Get Appointment](/api/appointments/get-appointment).
</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                                                                                                            |
| ------ | ---------------------------------------------------------------------------------------------------------------------- |
| `403`  | Forbidden — your API key does not have access to this operation or the shipment is outside your access context.        |
| `404`  | Shipment not found.                                                                                                    |
| `409`  | Shipment cannot be cancelled (already picked up, delivered, or cancelled).                                             |
| `500`  | Internal server error.                                                                                                 |
| `502`  | Logistics provider rejected the request (e.g., cancellation deadline exceeded). Includes the provider's error message. |

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

<ResponseExample>
  ```json 200 theme={null}
  {
    "id": "P2604154821",
    "status": "cancelled",
    "logistics_provider": "go",
    "tracking_number": "GO1234567890",
    "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": [],
    "appointments": [],
    "created_at": "2026-04-03T14:30:00Z",
    "updated_at": "2026-04-03T16:45:00Z"
  }
  ```

  ```json 409 theme={null}
  {
    "error": "Shipment cannot be cancelled after pickup"
  }
  ```

  ```json 404 theme={null}
  {
    "error": "Shipment not found"
  }
  ```

  ```json 502 theme={null}
  {
    "error": "Logistics provider error: The cancellation notice period has already been exceeded. Cancellation is no longer possible via the web service. Please contact the GO! station.",
    "logistics_error_code": 4006
  }
  ```
</ResponseExample>