# 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](https://en.wikipedia.org/wiki/ISO_8601)) `2024-07-25T15:24:46.657Z` | | `modified_at_end` | *date string* | ([ISO 8601 Standard](https://en.wikipedia.org/wiki/ISO_8601)) `2024-07-25T15:24:46.657Z` | | `created_at_start` | *date string* | ([ISO 8601 Standard](https://en.wikipedia.org/wiki/ISO_8601)) `2024-07-25T15:24:46.657Z` | | `created_at_end` | *date string* | ([ISO 8601 Standard](https://en.wikipedia.org/wiki/ISO_8601)) `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. ```http 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** ```json { "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** ```http GET /v2/shipments/se-202902255 HTTP/1.1 Host: api.shipstation.com API-Key: __YOUR_API_KEY_HERE__ ``` **Response** ```json { "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** ```http 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.