Shipments

List shipments, or read one with its complete event history. Needs a key with the shipments:read scope.

List shipments

GET/v1/shipmentsScope: shipments:read

Newest update first. All filters are optional and can be combined.

Parameter	Type	Description
status	string	One of the shipment statuses. Any other value returns `400 invalid_parameter`.
tracking_id	string	Exact ZLG tracking number.
customer_id	string	Only shipments of this customer.
updated_since	ISO 8601	Only shipments updated at or after this moment, e.g. `2026-10-01` or `2026-10-01T12:00:00Z`.
limit	integer	1 to 100, default 25.
cursor	string	From the previous page. See Pagination.

curl

curl -H "Authorization: Bearer zlx_live_YOUR_KEY" \
  "https://api.zargologix.com/v1/shipments?status=IN_TRANSIT&updated_since=2026-10-01&limit=50"

Get one shipment

GET/v1/shipments/{id}Scope: shipments:read

{id} can be the shipment's internal id, its ZLG tracking number or its ZSH shipment reference. The response is the shipment object plus an events array, oldest first. An unknown id returns 404 not_found.

200 OK

{
  "id": "cm2k9x0a10001",
  "tracking_id": "ZLG90215772410",
  "reference": "ZSH-2026-00042",
  "booking_reference": "ZBK-2026-00012",
  "status": "IN_TRANSIT",
  "mode": "AIR",
  "service_level": "Express",
  "incoterm": "DAP",
  "customer_id": "cm2k8w7b20000",
  "source": "PUBLIC_BOOKING",
  "origin": { "city": "Sparks", "country": "United States" },
  "destination": { "city": "Accra", "country": "Ghana" },
  "sender": { "name": "Acme Parts Ltd", "email": "dispatch@acme.example" },
  "receiver": { "name": "Kwame Mensah", "email": "kwame@example.com", "phone": "+233200000000", "address": "12 Ring Road, Accra" },
  "package": { "description": "Machine parts", "quantity": 2, "weight_kg": "48.50", "declared_value": "1200.00", "currency": "USD" },
  "payment_status": "PAID",
  "shipping_cost": "310.00",
  "delivery_percentage": 40,
  "collection_date": "2026-10-09T08:00:00.000Z",
  "created_at": "2026-10-08T15:20:11.000Z",
  "updated_at": "2026-10-10T12:00:00.000Z",
  "events": [
    {
      "id": "cm2ka1b3c0004",
      "status": "PICKED_UP",
      "location": "Sparks, United States",
      "note": null,
      "latitude": 39.5349,
      "longitude": -119.7527,
      "created_at": "2026-10-09T08:00:00.000Z"
    }
  ]
}

The shipment object

Field	Type	Description
id	string	Internal id. Stable for the life of the shipment.
tracking_id	string	The ZLG tracking number customers use.
reference	string \| null	ZSH shipment reference.
booking_reference	string \| null	ZBK booking reference, if the shipment began as a booking.
status	string	Current status. See Status values.
mode	string	`AIR`, `SEA`, `ROAD` or `RAIL`.
service_level	string \| null	Service level chosen for the shipment.
incoterm	string \| null	Incoterm agreed for the shipment.
customer_id	string	The customer account that owns the shipment.
source	string	`ADMIN` (created by staff) or `PUBLIC_BOOKING` (from the website).
origin	object	`city` (may be null) and `country`.
destination	object	`city` (may be null) and `country`.
sender	object	`name`, `email` (may be null).
receiver	object	`name`, `email`, `phone`, `address`. Any of them may be null.
package	object	`description`, `quantity`, `weight_kg` (string), `declared_value` (string), `currency`.
payment_status	string	`UNPAID`, `PAID` or `PARTIAL`.
shipping_cost	string	Decimal amount, two places.
delivery_percentage	integer	Progress from 0 to 100.
collection_date	string \| null	Planned or actual collection time.
created_at	string	When the shipment was created.
updated_at	string	When it last changed.

The event object

Each time a shipment changes status, an event is recorded. They appear in events on the single-shipment response.

Field	Type	Description
id	string	Event id.
status	string	The status the shipment moved to.
location	string \| null	Where it happened, when known.
note	string \| null	Free text recorded by ZargoLogix staff with the update.
latitude	number \| null	Position, when known.
longitude	number \| null	Position, when known.
created_at	string	When the event was recorded.