Skip to main content
A shipment is a courier order for transporting blood samples or lab materials from a test location to a laboratory. The Shipments API lets you create, track, modify, and cancel shipment orders.
All shipment endpoints require the SHIPMENTS_MANAGE scope.

​
Creating a shipment

When creating a shipment, you specify the origin location_id — the test location where the courier should pick up. The destination laboratory is automatically determined based on the location’s configuration. The location must be within your API key’s access context. Use List Locations to find available location IDs.

​
Lifecycle

Shipments move through the following statuses: 
pending → shipped → in_transit → delivered
                        ↓
                      fault
     ↓
  cancelled
StatusMeaning
pendingThe shipment order has been created but the courier has not yet picked up.
shippedThe courier has acknowledged the order.
in_transitThe package is in transit to the destination.
deliveredThe package has been delivered.
faultA problem occurred during transit.
cancelledThe shipment has been cancelled.

​
Pickup schedule rules

The following rules apply when creating or updating a shipment’s pickup schedule:
RuleDetail
Weekdays onlypickup_date must be Monday–Friday.
Today or futurepickup_date cannot be in the past.
Same-day cutoffSame-day pickups are rejected after 16:00 Europe/Berlin.
Window rangepickup_time_from and pickup_time_till must be within 09:00–17:00.
Minimum 2h windowThe pickup window must be at least 2 hours wide.

​
Modifying shipments

You can update a shipment’s pickup schedule, package count, weight, and notes using PATCH /api/v1/shipments/{id}. If schedule-related fields change (pickup date or time), the existing logistics order is automatically cancelled and a new one is created. Updated schedule fields are validated against the same pickup schedule rules.
Shipments cannot be modified after the courier has picked up the package. Attempts to update a shipment in in_transit, delivered, or fault status return 409 Conflict.

​
Cancelling shipments

Cancel a shipment using DELETE /api/v1/shipments/{id}. This calls the logistics provider API to cancel the order and updates the status to cancelled.
Shipments cannot be cancelled after pickup. Attempts to cancel a shipment that is already in_transit, delivered, fault, or cancelled return 409 Conflict.

​
Shipment reference IDs

Each shipment is assigned a reference ID in the format P-YYMMDD-XXXX (e.g., P-260415-4821). Use this ID to retrieve, update, or cancel the shipment.

​
Shipment addresses

The origin and destination fields in the shipment response contain resolved address objects with the following structure: 
{
  "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"
}
These addresses are resolved from the location or preset you specified at creation time.

​
Example shipment

{
  "id": "P-260415-4821",
  "status": "pending",
  "logistics_provider": "go_express",
  "tracking_number": null,
  "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
  },
  "notes": "Handle with care — temperature-sensitive samples",
  "shipped_at": null,
  "arrived_at": null,
  "created_at": "2026-04-03T14:30:00Z",
  "updated_at": null
}