List Shipments

Obtains a list of shipments that match the specified criteria.

IMPORTANT

Only valid shipments with labels generated in ShipStation will be returned in the response.

Orders that have been marked as Shipped either through the UI or the API will not appear as they are considered external shipments.

To include each shipment's associated shipmentItems in the response, be sure to set the includeShipmentItems parameter to true.

When listing shipments, there is a maximum pagination offset of 10,000 results. The pagination offset is calculated as page × pageSize. If you attempt to request results beyond this offset, the API will return a 400 Bad Request error.

Examples:

• If pageSize=1, the maximum page you can request is 10,000
• If pageSize=50 (default), the maximum page you can request is 200 (200 × 50 = 10,000)
• If pageSize=500, the maximum page you can request is 20 (20 × 500 = 10,000)

Error Response Example:

{
  "request_id": "f41e6bc1-69f0-4b09-b0ab-cd2a3e4f5678",
  "errors": [
    {
      "error_source": "shipengine",
      "error_type": "validation",
      "error_code": "invalid_field_value",
      "message": "Pagination offset exceeds the maximum allowed value of 10000. Please narrow your query using filters such as modifyDateStart/modifyDateEnd.",
      "field_name": "page",
      "field_value": "20000"
    }
  ]
}

How to work around this limit:

If you encounter this pagination limit, add filtering parameters to narrow your results:

• Use date range filters like modifyDateStart and modifyDateEnd or createDateStart and createDateEnd
• Filter by orderStatus, storeId, or carrierCode

curl -i -X GET \
  -u <username>:<password> \
  'https://ssapi.shipstation.com/shipments?recipientName=string&recipientCountryCode=string&orderNumber=string&orderId=0&carrierCode=string&serviceCode=string&trackingNumber=string&createDateStart=2019-08-24T14%3A15%3A22Z&createDateEnd=2019-08-24T14%3A15%3A22Z&shipDateStart=2019-08-24&shipDateEnd=2019-08-24&voidDateStart=2019-08-24T14%3A15%3A22Z&voidDateEnd=2019-08-24T14%3A15%3A22Z&storeId=0&includeShipmentItems=false&sortBy=ShipDate&sortDir=ASC&page=1&pageSize=100'

• Create Shipment Label
• Get Rates