---
title: "List shipments"
method: GET
path: "/shipments"
tags: ["shipments"]
---

# List shipments

`GET /shipments`

Obtains a list of shipments that match the specified criteria.

**Note:** Only valid shipments with labels generated in ShipStation will be returned. Orders that have been marked as Shipped through the UI or API will not appear as they are considered external shipments.

## Query parameters

- `recipientName` string
- `recipientCountryCode` string
- `orderNumber` string
- `orderId` integer
- `carrierCode` string
- `serviceCode` string
- `trackingNumber` string
- `createDateStart` string, date-time
- `createDateEnd` string, date-time
- `shipDateStart` string, date
- `shipDateEnd` string, date
- `voidDateStart` string, date-time
- `voidDateEnd` string, date-time
- `storeId` integer
- `includeShipmentItems` boolean
- `sortBy` 'ShipDate' | 'CreateDate'
- `sortDir` 'ASC' | 'DESC'
- `page` integer
- `pageSize` integer

## Response `200`

List of shipments retrieved successfully

- object
  - `shipments` object[]
    - `shipmentId` integer
    - `orderId` integer
    - `orderKey` string
    - `userId` string
    - `orderNumber` string
    - `createDate` string, date-time
    - `shipDate` string, date
    - `shipmentCost` number
    - `insuranceCost` number
    - `trackingNumber` string
    - `isReturnLabel` boolean
    - `batchNumber` string, nullable
    - `carrierCode` string
    - `serviceCode` string
    - `packageCode` string
    - `confirmation` string
    - `warehouseId` integer, nullable
    - `voided` boolean
    - `voidDate` string, date-time, nullable
    - `marketplaceNotified` boolean
    - `notifyErrorMessage` string, nullable
    - `shipTo` Address — Physical address for shipping or billing
      - `name` string — Name of the recipient
      - `company` string, nullable — Company name
      - `street1` string — First line of the street address
      - `street2` string, nullable — Second line of the street address
      - `street3` string, nullable — Third line of the street address
      - `city` string — City name
      - `state` string — State or province code
      - `postalCode` string — Postal or ZIP code
      - `country` string — Two-letter ISO country code
      - `phone` string, nullable — Phone number
      - `residential` boolean, nullable — Whether the address is residential
      - `addressVerified` string, nullable — Address verification status
    - `weight` Weight — Weight measurement
      - `value` number, required — Weight value
      - `units` 'pounds' | 'ounces' | 'grams', required — Weight unit of measurement
    - `dimensions` Dimensions — Package dimensions
      - `length` number, required — Length
      - `width` number, required — Width
      - `height` number, required — Height
      - `units` 'inches' | 'centimeters', required — Dimension unit of measurement
    - `insuranceOptions` InsuranceOptions — Shipping insurance options
      - `provider` 'none' | 'carrier' | 'xcover' | 'parcelguard' | 'shipsurance', nullable — Insurance provider
      - `insureShipment` boolean — Whether to insure the shipment
      - `insuredValue` number — Insured value amount
    - `advancedOptions` AdvancedOptions — Advanced shipping options
      - `warehouseId` integer, nullable — Warehouse ID
      - `nonMachinable` boolean — Whether the package is non-machinable
      - `saturdayDelivery` boolean — Whether to deliver on Saturday
      - `containsAlcohol` boolean — Whether the package contains alcohol
      - `mergedOrSplit` boolean — Whether this is a merged or split order
      - `mergedIds` integer[] — Array of merged order IDs
      - `parentId` integer, nullable — Parent order ID for split orders
      - `storeId` integer, nullable — Store ID
      - `customField1` string, nullable — Custom field 1
      - `customField2` string, nullable — Custom field 2
      - `customField3` string, nullable — Custom field 3
      - `source` string, nullable — Order source
      - `billToParty` string, nullable — Bill to party
      - `billToAccount` string, nullable — Bill to account
      - `billToPostalCode` string, nullable — Bill to postal code
      - `billToCountryCode` string, nullable — Bill to country code
      - `movementIndicator` 'c2c' | 'b2c' | 'c2b' | 'b2b', nullable — An indicator that will tell the carrier the type of movement for the shipment.
    - `labelData` string, nullable — Base64 encoded PDF label data
    - `formData` string, nullable
  - `total` integer — Total number of shipments
  - `page` integer — Current page number
  - `pages` integer — Total number of pages

## Other responses

- `400` — Bad Request - The request could not be understood or was missing required parameters
- `401` — Unauthorized - Authentication credentials are missing or invalid
- `500` — Internal Server Error - An error occurred on the server

---

[API](https://skmtc.net/shipstation/apis/shipstation-v1-api-legacy.md) · [All operations](https://skmtc.net/shipstation/apis/shipstation-v1-api-legacy/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/shipstation/shipstation-v1-api-legacy/revisions/c71c20d26559/schema)