List shipments

GET /shipments

Returns your shipments, most recently created first, optionally filtered by status.

Query parameters

ParameterTypeDescription
status string optional Only return shipments with this status. One of: label_created, in_transit, out_for_delivery, delivered, cancelled.
limit integer optional Maximum number of shipments to return. Minimum 1. Maximum 100.

Example request

curl -X GET "https://api.parcelly.dev/v1/shipments?status=in_transit&limit=20" \
  -H "Authorization: Bearer $PARCELLY_API_KEY"

Responses

200 A page of shipments.

FieldTypeDescription
data array required The shipments on this page.
data[].id string required Unique identifier of the shipment.
data[].status string required Current state of the shipment. One of: label_created, in_transit, out_for_delivery, delivered, cancelled.
data[].tracking_number string required Carrier tracking number.
data[].carrier string required ID of the carrier handling the shipment.
data[].price number required Shipping price in USD.
data[].created_at string (date-time) required When the shipment was created.
data[].estimated_delivery string (date) optional Estimated delivery date, once known.
has_more boolean required Whether more shipments exist beyond this page.

Example response

{
  "data": [
    {
      "id": "shp_7Hk2mQ9x",
      "status": "in_transit",
      "tracking_number": "PCL1234567890",
      "carrier": "swiftpost",
      "price": 12.5,
      "created_at": "2026-01-20T09:30:00Z",
      "estimated_delivery": "2026-01-23"
    }
  ],
  "has_more": false
}