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

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

Example Request & Response

Get Shipment by ID

Example Request & Response

Get Shipment by External ID

Example Request & Response

Was this helpful?