# List 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.

Endpoint: GET /shipments
Version: 1.0.0
Security: basicAuth

## Query parameters:

  - `recipientName` (string)
    Returns shipments shipped to the specified recipient name

  - `recipientCountryCode` (string)
    Returns shipments shipped to the specified country code (two-letter ISO)

  - `orderNumber` (string)
    Returns shipments whose orders have the specified order number

  - `orderId` (integer)
    Returns shipments whose orders have the specified order ID

  - `carrierCode` (string)
    Returns shipments shipped with the specified carrier

  - `serviceCode` (string)
    Returns shipments shipped with the specified shipping service

  - `trackingNumber` (string)
    Returns shipments with the specified tracking number

  - `createDateStart` (string)
    Returns shipments created on or after the specified date

  - `createDateEnd` (string)
    Returns shipments created on or before the specified date

  - `shipDateStart` (string)
    Returns shipments with shipDate on or after the specified date

  - `shipDateEnd` (string)
    Returns shipments with shipDate on or before the specified date

  - `voidDateStart` (string)
    Returns shipments voided on or after the specified date

  - `voidDateEnd` (string)
    Returns shipments voided on or before the specified date

  - `storeId` (integer)
    Returns shipments whose orders belong to the specified store ID

  - `includeShipmentItems` (boolean)
    Specifies whether to include shipment items with results

  - `sortBy` (string)
    Sort the responses by a set value. If left empty, the response will be sorted by ascending createDate.
    Enum: "ShipDate", "CreateDate"

  - `sortDir` (string)
    Sort direction
    Enum: "ASC", "DESC"

  - `page` (integer)
    Page number

  - `pageSize` (integer)
    Number of results per page. Maximum 500.

## Response 200 fields (application/json):

  - `shipments` (array)

  - `shipments.shipmentId` (integer)
    Example: 33974374

  - `shipments.orderId` (integer)
    Example: 43945660

  - `shipments.orderKey` (string)
    Example: "8061c220f0794a9b92460b8bae6837e4"

  - `shipments.userId` (string)
    Example: "123456AB-ab12-3c4d-5e67-89f1abc1defa"

  - `shipments.orderNumber` (string)
    Example: "100038-1"

  - `shipments.createDate` (string)
    Example: "2014-10-03T06:51:33Z"

  - `shipments.shipDate` (string)
    Example: "2014-10-03"

  - `shipments.shipmentCost` (number)
    Example: 1.93

  - `shipments.insuranceCost` (number)

  - `shipments.trackingNumber` (string)
    Example: "9400111899561704681189"

  - `shipments.isReturnLabel` (boolean)

  - `shipments.batchNumber` (any)
    Example: "100301"

  - `shipments.carrierCode` (string)
    Example: "stamps_com"

  - `shipments.serviceCode` (string)
    Example: "usps_first_class_mail"

  - `shipments.packageCode` (string)
    Example: "package"

  - `shipments.confirmation` (string)
    Example: "delivery"

  - `shipments.warehouseId` (any)
    Example: 16079

  - `shipments.voided` (boolean)

  - `shipments.voidDate` (any)

  - `shipments.marketplaceNotified` (boolean)
    Example: true

  - `shipments.notifyErrorMessage` (any)

  - `shipments.shipTo` (object)
    Physical address for shipping or billing

  - `shipments.shipTo.name` (string)
    Name of the recipient
    Example: "John Doe"

  - `shipments.shipTo.company` (any)
    Company name
    Example: "Acme Corp"

  - `shipments.shipTo.street1` (string)
    First line of the street address
    Example: "123 Main St"

  - `shipments.shipTo.street2` (any)
    Second line of the street address
    Example: "Apt 4B"

  - `shipments.shipTo.street3` (any)
    Third line of the street address
    Example: "Building B"

  - `shipments.shipTo.city` (string)
    City name
    Example: "Austin"

  - `shipments.shipTo.state` (string)
    State or province code
    Example: "TX"

  - `shipments.shipTo.postalCode` (string)
    Postal or ZIP code
    Example: "78701"

  - `shipments.shipTo.country` (string)
    Two-letter ISO country code
    Example: "US"

  - `shipments.shipTo.phone` (any)
    Phone number
    Example: "512-555-1234"

  - `shipments.shipTo.residential` (any)
    Whether the address is residential
    Example: true

  - `shipments.shipTo.addressVerified` (any)
    Address verification status
    Example: "Address validated successfully"

  - `shipments.weight` (object)
    Weight measurement

  - `shipments.weight.value` (number, required)
    Weight value
    Example: 24

  - `shipments.weight.units` (string, required)
    Weight unit of measurement
    Enum: "pounds", "ounces", "grams"

  - `shipments.dimensions` (any)

  - `shipments.insuranceOptions` (object)
    Shipping insurance options

  - `shipments.insuranceOptions.provider` (any)
    Insurance provider
    Enum: "none", "carrier", "shipsurance"

  - `shipments.insuranceOptions.insureShipment` (boolean)
    Whether to insure the shipment
    Example: true

  - `shipments.insuranceOptions.insuredValue` (number)
    Insured value amount
    Example: 200

  - `shipments.advancedOptions` (any)

  - `shipments.shipmentItems` (array)

  - `shipments.labelData` (any)
    Base64 encoded PDF label data

  - `shipments.formData` (any)

  - `total` (integer)
    Total number of shipments
    Example: 2

  - `page` (integer)
    Current page number
    Example: 1

  - `pages` (integer)
    Total number of pages
    Example: 1

## Response 400 fields (application/json):

  - `message` (string)
    Example: "Invalid request parameters"

## Response 401 fields (application/json):

  - `message` (string)
    Example: "Invalid API credentials"

## Response 500 fields (application/json):

  - `message` (string)
    Example: "An internal error occurred"