Shipments
Update Shipment
Modify shipment details before pickup
PATCH
/
api
/
v1
/
shipments
/
{id}
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"
}'
{
"id": "P2604154821",
"status": "pending",
"logistics_provider": "go",
"tracking_number": null,
"contents": "Medizinisch freigestellte Probe",
"booked_by": "aniva",
"paired_with": null,
"origin": {
"name": "Aniva Berlin Mitte",
"company_name": null,
"street": "Unter den Linden",
"house_number": "42",
"address_line_2": null,
"postal_code": "10117",
"city": "Berlin",
"state": null,
"country_code": "DE",
"phone": "+4930987654321",
"email": "berlin-mitte@anivahealth.com"
},
"destination": {
"name": "LabClinic GmbH",
"company_name": null,
"street": "Laborstraße",
"house_number": "10",
"address_line_2": null,
"postal_code": "80331",
"city": "München",
"state": null,
"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": [],
"home_kit_orders": [],
"synced_at": "2026-04-03T15:00:00Z",
"created_at": "2026-04-03T14:30:00Z",
"updated_at": "2026-04-03T15:10:00Z"
}
{
"error": "Shipment cannot be modified after pickup"
}
{
"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
}
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.
A home-kit parcel already has its label printed, so only
Shipments cannot be modified after pickup. Attempting to update a shipment that has already been
picked up returns
409 Conflict.notes can change. A new pickup window
or weight on a home-kit parcel returns 409 Conflict; cancel it and create a new shipment instead.
To update a home-kit parcel, every linked home-kit order must be in your access context.
Otherwise the call returns 403. See Access.
Request
Path parameters
string
required
Shipment reference ID (e.g.,
P2604154821).Body parameters
All body parameters are optional — only include the fields you want to change.string
New pickup date in
YYYY-MM-DD format, interpreted in the origin location’s timezone.string
New earliest pickup time in
HH:MM format, interpreted as wall-clock time in the origin
location’s timezone.string
New latest pickup time in
HH:MM format, interpreted as wall-clock time in the origin location’s
timezone.integer
New number of packages.
number
New weight in kg.
string
New notes or remarks. Maximum 128 characters.
Response
On success, the API returns200 OK with the updated shipment.
string
required
Shipment reference identifier.
string
required
Shipment lifecycle status. One of
pending, in_transit, delivered, fault, or cancelled.string
required
Logistics provider. One of
go, dhl_parcel, dhl_warenpost, tof, rotrunner, rapido or
ups. A home-kit parcel is dhl_parcel, or dhl_warenpost when it goes abroad as Warenpost
International.string
External tracking number from the logistics provider. May be
null.string
Free-text description of what is in the parcel, as given at creation. May be
null.string
required
Who printed the label:
aniva or external. Only aniva shipments accept this call.string
Reference of the other parcel of a two-parcel consignment.
null for a one-way parcel.object
Pickup address. May be
null.Show address object
Show address object
string
required
Recipient, company, or location name.
string
Company / c/o line. May be
null.string
required
Street name, without the house number.
string
House number. May be
null.string
Building, entrance, or floor. May be
null.string
required
City.
string
State or province. May be
null.string
required
Postal/ZIP code.
string
required
ISO 3166-1 alpha-2 country code.
string
Contact phone number. May be
null.string
Contact email. May be
null.object
Delivery address. Same structure as
origin. May be null.object
Scheduled pickup window. May be
null.Show pickup object
Show pickup object
string
Optional notes. May be
null.object[]
required
Chronological lifecycle events from the logistics provider (oldest first). Each entry has
state, code, detail_code, status, description, location and time. See Get
Shipment for each field. Empty array if no events observed yet.ShipmentAppointmentLink[]
required
Appointments linked to this shipment, oldest-link first. Each entry is
{ id, added_at };
cross-reference each id against Get Appointment.
Only the appointments in your access context are listed.ShipmentHomeKitOrderLink[]
required
Home-kit orders linked to this shipment, oldest-link first, in the same
{ id, added_at } shape.
Only the orders in your access context are listed. Empty array for practice parcels.string
When the shipment was last reconciled with its carrier, as a UTC instant.
null until the first
sync.string
required
Creation timestamp (ISO 8601).
string
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, the shipment is outside your access context, or a linked home-kit order is outside your access context. |
404 | Shipment not found. |
409 | Shipment cannot be modified after pickup, or it is a home-kit parcel whose label is printed and the request changes more than notes. |
501 | The shipment is external — it was not booked through Aniva and cannot be changed here. |
500 | Internal server error. |
502 | Logistics provider rejected the request (e.g., cancellation or re-creation failed). Includes the provider’s error message. |
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"
}'
{
"id": "P2604154821",
"status": "pending",
"logistics_provider": "go",
"tracking_number": null,
"contents": "Medizinisch freigestellte Probe",
"booked_by": "aniva",
"paired_with": null,
"origin": {
"name": "Aniva Berlin Mitte",
"company_name": null,
"street": "Unter den Linden",
"house_number": "42",
"address_line_2": null,
"postal_code": "10117",
"city": "Berlin",
"state": null,
"country_code": "DE",
"phone": "+4930987654321",
"email": "berlin-mitte@anivahealth.com"
},
"destination": {
"name": "LabClinic GmbH",
"company_name": null,
"street": "Laborstraße",
"house_number": "10",
"address_line_2": null,
"postal_code": "80331",
"city": "München",
"state": null,
"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": [],
"home_kit_orders": [],
"synced_at": "2026-04-03T15:00:00Z",
"created_at": "2026-04-03T14:30:00Z",
"updated_at": "2026-04-03T15:10:00Z"
}
{
"error": "Shipment cannot be modified after pickup"
}
{
"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
}
⌘I
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"
}'
{
"id": "P2604154821",
"status": "pending",
"logistics_provider": "go",
"tracking_number": null,
"contents": "Medizinisch freigestellte Probe",
"booked_by": "aniva",
"paired_with": null,
"origin": {
"name": "Aniva Berlin Mitte",
"company_name": null,
"street": "Unter den Linden",
"house_number": "42",
"address_line_2": null,
"postal_code": "10117",
"city": "Berlin",
"state": null,
"country_code": "DE",
"phone": "+4930987654321",
"email": "berlin-mitte@anivahealth.com"
},
"destination": {
"name": "LabClinic GmbH",
"company_name": null,
"street": "Laborstraße",
"house_number": "10",
"address_line_2": null,
"postal_code": "80331",
"city": "München",
"state": null,
"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": [],
"home_kit_orders": [],
"synced_at": "2026-04-03T15:00:00Z",
"created_at": "2026-04-03T14:30:00Z",
"updated_at": "2026-04-03T15:10:00Z"
}
{
"error": "Shipment cannot be modified after pickup"
}
{
"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
}