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’ll add query parameters to filter which shipments are returned in the response. 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
`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`

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.