> ## 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.
# Update Shipment
> Modify shipment details before pickup
Update shipment details such as pickup schedule, package count, or notes. If any logistics-relevant fields change (pickup date, time, package count, or weight), the existing logistics order is cancelled and a new one is created automatically. Fields you omit are preserved from the existing shipment. Updated schedule fields are validated against the [pickup schedule rules](/concepts/shipments#pickup-schedule-rules).
Shipments cannot be modified after pickup. Attempting to update a shipment that has already been
picked up returns `409 Conflict`.
## Request
### Path parameters
Shipment reference ID (e.g., `P2604154821`).
### Body parameters
All body parameters are optional — only include the fields you want to change.
New pickup date in `YYYY-MM-DD` format, interpreted in the origin location's timezone.
New earliest pickup time in `HH:MM` format, interpreted as wall-clock time in the origin
location's timezone.
New latest pickup time in `HH:MM` format, interpreted as wall-clock time in the origin location's
timezone.
New number of packages.
New weight in kg.
New notes or remarks. Maximum 128 characters.
## Response
On success, the API returns `200 OK` with the updated shipment.
Shipment reference identifier.
Shipment lifecycle status. One of `pending`, `in_transit`, `delivered`, `fault`, or `cancelled`.
Logistics provider. One of `go`, `dhl_parcel`, `tof`, `rotrunner` or `rapido`. Every home-kit
parcel is `dhl_parcel`.
External tracking number from the logistics provider. May be `null`.
Pickup address. May be `null`.
Recipient, company, or location name.
Company / c/o line. May be `null`.
Street name, without the house number.
House number. May be `null`.
Building, entrance, or floor. May be `null`.
City.
State or province. May be `null`.
Postal/ZIP code.
ISO 3166-1 alpha-2 country code.
Contact phone number. May be `null`.
Contact email. May be `null`.
Delivery address. Same structure as `origin`. May be `null`.
Scheduled pickup window. May be `null`.
Start of pickup window as a UTC instant (ISO 8601 with `Z` suffix).
End of pickup window as a UTC instant (ISO 8601 with `Z` suffix).
IANA timezone of the pickup location (e.g., `Europe/Berlin`). Use to render `from` / `till` in pickup-location wall-clock.
Optional notes. May be `null`.
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.
Appointments linked to this shipment, oldest-link first. Each entry is `{ id, added_at }`;
cross-reference each `id` against [Get Appointment](/api/appointments/get-appointment).
Creation timestamp (ISO 8601).
Last update timestamp (ISO 8601). May be `null`.
## Error responses
| Status | Description |
| ------ | -------------------------------------------------------------------------------------------------------------------------- |
| `400` | Validation error — e.g., invalid date or time 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. |
| `409` | Shipment cannot be modified after pickup. |
| `500` | Internal server error. |
| `502` | Logistics provider rejected the request (e.g., cancellation or re-creation failed). Includes the provider's error message. |
```bash cURL theme={null}
curl --request PATCH \
--url https://anivahealth.com/api/v1/shipments/P2604154821 \
--header 'x-api-key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"pickup_date": "2026-04-16",
"pickup_time_from": "10:00",
"pickup_time_till": "13:00"
}'
```
```json 200 theme={null}
{
"id": "P2604154821",
"status": "pending",
"logistics_provider": "go",
"tracking_number": null,
"origin": {
"name": "Aniva Berlin Mitte",
"street": "Unter den Linden",
"house_number": "42",
"postal_code": "10117",
"city": "Berlin",
"country_code": "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_code": "DE",
"phone": null,
"email": null
},
"pickup": {
"from": "2026-04-16T08:00:00Z",
"till": "2026-04-16T11:00:00Z",
"timezone": "Europe/Berlin"
},
"notes": null,
"status_updates": [],
"appointments": [],
"created_at": "2026-04-03T14:30:00Z",
"updated_at": "2026-04-03T15:10:00Z"
}
```
```json 409 theme={null}
{
"error": "Shipment cannot be modified after pickup"
}
```
```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
}
```