List Shipments

Retrieve shipments belonging to the current workspace. Results are returned in reverse-chronological order and support cursor-based pagination. You can also filter by date range.

---

Endpoint

GET/v1/shipments

Required permission: shipments:get

---

Query Parameters

Parameter	Type	Required	Description
limit	Integer	❌	Max records per page. Defaults to 20.
cursor	String	❌	Opaque pagination cursor returned from a previous response. Pass this to fetch the next page.
startDate	String	❌	ISO 8601 date to filter from (e.g. 2026-07-01T00:00:00Z).
endDate	String	❌	ISO 8601 date to filter until (e.g. 2026-07-31T23:59:59Z).

---

Response

Returns a paginated list of shipment summaries.

Top-level fields

Field	Type	Description
items	Array	List of shipment summary records. See fields below.
nextCursor	String?	Cursor to pass as cursor in the next request. null when there are no more pages.

Item fields

Field	Type	Description
id	String	Internal shipment ID.
trackingCode	String	Customer-facing tracking code.
senderName	String	Sender's name.
senderPhone	String	Sender's phone.
senderEmail	String?	Sender's email, if provided.
receiverName	String	Recipient's name.
receiverPhone	String	Recipient's phone.
receiverEmail	String?	Recipient's email, if provided.
originAddress	String	Pickup address.
destinationAddress	String	Delivery address.
packageTitle	String	Package label.
totalCost	Integer	Amount charged in ₦.
status	String	Current status. PENDING, SCHEDULED, CANCELED, or DELIVERED.
createdAt	String	ISO 8601 creation timestamp.

---

{
"statusCode": 200,
"message": "Success",
"data": {
  "items": [
    {
      "id": "SHP_Z8F9A2B3C4",
      "trackingCode": "TCL-SB-3891829",
      "senderName": "Grace Adegoke",
      "senderPhone": "+2348031234567",
      "receiverName": "John Doe",
      "receiverPhone": "+2348123456789",
      "originAddress": "12 Allen Avenue, Ikeja, Lagos",
      "destinationAddress": "Ring Road, Ibadan, Oyo",
      "packageTitle": "Laptop & Charger",
      "totalCost": 33040,
      "status": "PENDING",
      "createdAt": "2026-07-01T17:42:00Z"
    }
  ],
  "nextCursor": null
}
}