List Shipments

Obtains a list of shipments that match the specified criteria.

NOTE 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 every shipment's associated shipmentItems in the response, be sure to set the includeShipmentItems parameter to true.

All of the available filters are optional. They do not need to be included in the URL. If you do include them, here's what the URL may look like:

URL format with filters:

shipments?recipientName={recipientName}
&recipientCountryCode={recipientCountryCode}
&orderNumber={orderNumber}
&orderId={orderId}
&carrierCode={carrierCode}
&trackingNumber={trackingNumber}
&createDateStart={createDateStart}
&createDateEnd={createDateEnd}
&shipDateStart={shipDateStart}
&shipDateEnd={shipDateEnd}
&voidDateStart={voidDateStart}
&voidDateEnd={voidDateEnd}
&storeId={storeId}
&includeShipmentItems={includeShipmentItems}
&sortBy={sortBy}
&sortDir={sortDir}
&page={page}
&pageSize={pageSize}
Name Data Type Description
recipientName string Returns shipments shipped to the specified recipient name.

Optional
recipientCountryCode string Returns shipments shipped to the specified country code. Please use the two-letter ISO Origin Country code

Optional
orderNumber string Returns shipments whose orders have the specified order number.

Optional
orderId number Returns shipments whose orders have the specified order ID.

Optional
carrierCode string Returns shipments shipped with the specified carrier.

Optional
trackingNumber string Returns shipments with the specified tracking number.

Optional
customsCountryCode string The default two-letter ISO Origin Country code for the Product.

Optional
createDateStart string Returns shipments created on or after the specified createDate.

Optional
createDateEnd string Returns shipments created on or before the specified createDate.

Optional
shipDateStart string Returns shipments with the shipDate on or after the specified date.

Optional
shipDateEnd string Returns shipments with the shipDate on or before the specified date.

Optional
voidDateStart string Returns shipments voided on or after the specified date.

Optional
voidDateEnd string Returns shipments voided on or before the specified date.

Optional
storeId number Returns shipments whose orders belong to the specified store ID.

Optional
includeShipmentItems boolean Specifies whether to include shipment items with results Default value: false.

Optional
sortBy string Sort the responses by a set value.
The response will be sorted based on the ascending dates (oldest to most current.)
Values:
  • ShipDate
  • CreateDate
If left empty, the response will be sorted by ascending createDate.

Optional
sortDir string Sets the direction of the sort order.
Values:
  • ASC
  • DESC


Optional
page number Page number.

Optional
pageSize number Page size.

Optional

Example Request

GET /shipments?recipientName=recipientName&recipientCountryCode=recipientCountryCode&orderNumber=orderNumber&orderId=orderId&carrierCode=carrierCode&serviceCode=serviceCode&trackingNumber=trackingNumber&createDateStart=createDateStart&createDateEnd=createDateEnd&shipDateStart=shipDateStart&shipDateEnd=shipDateEnd&voidDateStart=voidDateStart&voidDateEnd=voidDateEnd&storeId=storeId&includeShipmentItems=includeShipmentItems&sortBy=sortBy&sortDir=sortDir&page=page&pageSize=pageSize HTTP/1.1
Host: ssapi.shipstation.com
Authorization: __YOUR_AUTH_HERE__

Example Response

{
  "shipments": [
    {
      "shipmentId": 33974374,
      "orderId": 43945660,
      "orderKey": "8061c220f0794a9b92460b8bae6837e4",
      "userId": "123456AB-ab12-3c4d-5e67-89f1abc1defa",
      "orderNumber": "100038-1",
      "createDate": "2014-10-03T06:51:33.6270000",
      "shipDate": "2014-10-03",
      "shipmentCost": 1.93,
      "insuranceCost": 0,
      "trackingNumber": "9400111899561704681189",
      "isReturnLabel": false,
      "batchNumber": "100301",
      "carrierCode": "stamps_com",
      "serviceCode": "usps_first_class_mail",
      "packageCode": "package",
      "confirmation": "delivery",
      "warehouseId": 16079,
      "voided": false,
      "voidDate": null,
      "marketplaceNotified": true,
      "notifyErrorMessage": null,
      "shipTo": {
        "name": "Yoda",
        "company": "",
        "street1": "12223 LOWDEN LN",
        "street2": "",
        "street3": null,
        "city": "MANCHACA",
        "state": "TX",
        "postalCode": "78652-3602",
        "country": "US",
        "phone": "2101235544",
        "residential": null
      },
      "weight": {
        "value": 1,
        "units": "ounces"
      },
      "dimensions": null,
      "insuranceOptions": {
        "provider": null,
        "insureShipment": false,
        "insuredValue": 0
      },
      "advancedOptions": null,
      "shipmentItems": [
        {
          "orderItemId": 56568665,
          "lineItemKey": null,
          "sku": "SQ3785739",
          "name": "Potato Kitten -",
          "imageUrl": null,
          "weight": null,
          "quantity": 1,
          "unitPrice": 1,
          "warehouseLocation": null,
          "options": null,
          "productId": 7565777,
          "fulfillmentSku": null
        }
      ],
      "labelData": null,
      "formData": null
    },
    {
      "shipmentId": 33974373,
      "orderId": 43337328,
      "userId": "123456AB-ab12-3c4d-5e67-89f1abc1defa",
      "orderNumber": "100028",
      "createDate": "2014-10-03T06:51:59.9430000",
      "shipDate": "2014-10-03",
      "shipmentCost": 1.93,
      "insuranceCost": 0,
      "trackingNumber": "9400111899561704681196",
      "isReturnLabel": false,
      "batchNumber": "100300",
      "carrierCode": "stamps_com",
      "serviceCode": "usps_first_class_mail",
      "packageCode": "package",
      "confirmation": "delivery",
      "warehouseId": 14265,
      "voided": false,
      "voidDate": null,
      "marketplaceNotified": true,
      "notifyErrorMessage": null,
      "shipTo": {
        "name": "Luke Skywalker",
        "company": "SS",
        "street1": "2815 EXPOSITION BLVD",
        "street2": "",
        "street3": null,
        "city": "AUSTIN",
        "state": "TX",
        "postalCode": "78703-1221",
        "country": "US",
        "phone": "",
        "residential": null
      },
      "weight": {
        "value": 1,
        "units": "ounces"
      },
      "dimensions": null,
      "insuranceOptions": {
        "provider": null,
        "insureShipment": false,
        "insuredValue": 0
      },
      "advancedOptions": null,
      "shipmentItems": [
        {
          "orderItemId": 55827278,
          "lineItemKey": null,
          "sku": "test",
          "name": "test",
          "imageUrl": null,
          "weight": null,
          "quantity": 1,
          "unitPrice": 1,
          "warehouseLocation": null,
          "options": null,
          "productId": 7541107,
          "fulfillmentSku": null
        }
      ],
      "labelData": null,
      "formData": null
    }
  ],
  "total": 2,
  "page": 1,
  "pages": 0
}