List Shipments

Since shipments power most of our services, you have a few ways to get the details you need about them. The following methods all use a GET call to the /v2/shipments endpoint.

List shipments: Get a list of shipments and their associated properties using query parameter(s) to filter which shipments are returned in the response.
Get shipment by ID: Get a single shipment and its associated properties using its shipment_id.
Get shipment by external ID: Get a single shipment and its associated properties using the external_shipment_id you assigned to it.

List Shipments

When you list shipments, you can add query parameters to filter which shipments are returned in the response. All query parameters are optional when listing shipments. By querying shipments, you expose a paged service that allows you to use multiple filters.

You can use the following query parameters:

Query Parameters	Type	Description
`batch_id`	string	Please note when filtering by `batch_id`: If you filter by batch, the API will ignore `shipment_status`, `modified_at_start`, `modified_at_end`, `created_at_start`, `created_at_end`, and `tag`. The API assumes you are opening a batch to view what's in the batch queue and `batch_id` is the only relevant filter since there are no other filters when executing a batch operation.
`tag`	string	Query by any shipment tags that may have been added to the shipment.
`shipment_status`	ennumerated string	`pending`, `processing`, `label_purchased`, `cancelled`
`modified_at_start`	date string	(ISO 8601 Standard) `2024-07-25T15:24:46.657Z`
`modified_at_end`	date string	(ISO 8601 Standard) `2024-07-25T15:24:46.657Z`
`created_at_start`	date string	(ISO 8601 Standard) `2024-07-25T15:24:46.657Z`
`created_at_end`	date string	(ISO 8601 Standard) `2024-07-25T15:24:46.657Z`
`page`	integer	defaults to 1
`page_size`	integer	defaults to 25
`sort_dir`	ennumerated string	`asc` or `desc`
`sort_by`	ennumerated string	`modified_at`, `created_at`
`sales_order_id`	string

Pagination Limits

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

Examples:

If page_size=1, the maximum page you can request is 10,000
If page_size=25 (default), the maximum page you can request is 400 (400 × 25 = 10,000)
If page_size=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 modified_at_start/modified_at_end.",
      "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 modified_at_start and modified_at_end or created_at_start and created_at_end
Filter by shipment_status, tag, or batch_id
Filter by sales_order_id

Need Help?

If you're having trouble working within this pagination limit or need assistance optimizing your shipment queries, please contact our API Support team.

Example Request & Response

GET /v2/shipments

In this example, we'll get a list of the last package we sent using the east_warehouse tag.

GET /v2/shipments?tag=east_warehouse&page=1&page_size=1&sort_dir=desc&sort_by=created_at HTTP/1.1
Host: api.shipstatione.com
API-Key: __YOUR_API_KEY_HERE__

Response

{
 "shipments": [
   {
     "shipment_id": "se-2102034",
     "carrier_id": "",
     "external_shipment_id": "1daa0c22-0519-46d0-8653-9f3dc62e7d2c",
     "ship_date": "2024-07-25T05:00:00.000Z",
     "created_at": "2024-07-25T15:24:46.657Z",
     "modified_at": "2024-07-25T15:24:46.657Z",
     "shipment_status": "pending",
     "ship_to": {
       "name": "Amanda Miller",
       "phone": "555-555-5555",
       "address_line1": "525 S Winchester Blvd",
       "city_locality": "San Jose",
       "state_province": "CA",
       "postal_code": "95128",
       "country_code": "US",
       "address_residential_indicator": "yes"
     },
     "ship_from": {
       "company_name": "Example Corp.",
       "name": "John Doe",
       "phone": "111-111-1111",
       "address_line1": "4009 Marathon Blvd",
       "address_line2": "Suite 300",
       "city_locality": "Austin",
       "state_province": "TX",
       "postal_code": "78756",
       "country_code": "US",
       "address_residential_indicator": "no"
     },
     "return_to": {
       "company_name": "Example Corp.",
       "name": "John Doe",
       "phone": "111-111-1111",
       "address_line1": "4009 Marathon Blvd",
       "address_line2": "Suite 300",
       "city_locality": "Austin",
       "state_province": "TX",
       "postal_code": "78756",
       "country_code": "US",
       "address_residential_indicator": "no"
     },
     "confirmation": "none",
     "advanced_options": {
       "bill_to_account": null,
       "bill_to_country_code": null,
       "bill_to_party": null,
       "bill_to_postal_code": null,
       "contains_alcohol": false,
       "custom_field1": null,
       "custom_field2": null,
       "custom_field3": null,
       "non_machinable": false,
       "saturday_delivery": false
     },
     "insurance_provider": "",
     "tags": [
       {
         "name": "east_warehouse"
       }
     ],
     "total_weight": {
       "value": 9.60,
       "units": "ounce"
     },
     "packages": [
       {
         "weight": {
           "value": 9.60,
           "units": "ounce"
         },
         "dimensions": {
           "units": "inch",
           "length": 12.00,
           "width": 7.10,
           "height": 6.00
         },
         "insured_value": {
           "currency": "usd",
           "amount": 0.0
         }
       }
     ]
   }
 ],
 "total": 1,
 "page": 1,
 "pages": 2,
 "links": {
   "first": {
     "href": "https://api.shipstation.com/v2/shipments?tag=east_warehouse&shipment_status=any&sort_dir=desc&sort_by=created_at&page=1&page_size=1"
   },
   "last": {
     "href": "https://api.shipstation.com/v2/shipments?tag=east_warehouse&shipment_status=any&sort_dir=desc&sort_by=created_at&page=2&page_size=1"
   },
   "prev": {},
   "next": {
     "href": "https://api.shipstation.com/v2/shipments?tag=east_warehouse&shipment_status=any&sort_dir=desc&sort_by=created_at&page=2&page_size=1"
   }
 }
}

Get Shipment by ID

With the shipment_id you can get a specific shipment’s details and properties.

Example Request & Response

GET /v2/shipments/:shipment_id

GET /v2/shipments/se-202902255 HTTP/1.1
Host: api.shipstation.com
API-Key: __YOUR_API_KEY_HERE__

Response

{
 "shipment_id": "se-202902255",
 "carrier_id": "se-123890",
 "service_code": "usps_priority_mail",
 "external_shipment_id": "0bcb569d-1727-4ff9-ab49-b2fec0cee5ae",
 "ship_date": "2024-02-12T00:00:00Z",
 "created_at": "2024-02-13T00:53:52.027Z",
 "modified_at": "2024-02-13T00:53:52.027Z",
 "shipment_status": "pending",
 "ship_to": {
   "name": "Amanda Miller",
   "phone": "555-555-5555",
   "address_line1": "525 S Winchester Blvd",
   "city_locality": "San Jose",
   "state_province": "CA",
   "postal_code": "95128",
   "country_code": "US",
   "address_residential_indicator": "yes"
 },
 "ship_from": {
   "company_name": "Example Corp.",
   "name": "John Doe",
   "phone": "111-111-1111",
   "address_line1": "4009 Marathon Blvd",
   "address_line2": "Suite 300",
   "city_locality": "Austin",
   "state_province": "TX",
   "postal_code": "78756",
   "country_code": "US",
   "address_residential_indicator": "no"
 },
 "warehouse_id": null,
 "return_to": {
   "company_name": "Example Corp.",
   "name": "John Doe",
   "phone": "111-111-1111",
   "address_line1": "4009 Marathon Blvd",
   "address_line2": "Suite 300",
   "city_locality": "Austin",
   "state_province": "TX",
   "postal_code": "78756",
   "country_code": "US",
   "address_residential_indicator": "no"
 },
 "insurance_provider": "none",
 "tags": [],
 "packages": [
   {
     "package_code": "package",
     "weight": {
       "value": 1.00,
       "unit": "ounce"
     },
     "dimensions": {
       "unit": "inch",
       "length": 0.0,
       "width": 0.0,
       "height": 0.0
     },
     "insured_value": {
       "currency": "usd",
       "amount": 0.00
     },
     "label_messages": {
       "reference1": null,
       "reference2": null,
       "reference3": null
     }
   }
 ],
 "total_weight": {
   "value": 1.00,
   "unit": "ounce"
 }
}

Get Shipment by External ID

If you assigned an external_shipment_id when creating the shipment, you can use a similar method as getting a shipment by ID.

Example Request & Response

GET /v2/shipments/external_shipment_id/:external_shipment_id

GET /v2/shipments/external_shipment_id/0bcb569d-1727-4ff9-ab49-b2fec0cee5ae HTTP/1.1
Host: api.shipstation.com
API-Key: __YOUR_API_KEY_HERE__

You’ll receive the same response as with the GET shipment by ID request.

List Shipments

List Shipments

Pagination Limits

Example Request & Response

Get Shipment by ID

Example Request & Response

Get Shipment by External ID

Example Request & Response

Was this helpful?