shipments
List shipments
<aside class="access" aria-label="Endpoint access"> <table class="access__table"> <thead> <tr> <th class="access__table-header">Products</th> <th class="access__table-header">Plans</th> </tr> </thead> <tbody> <tr> <td class="access__table-cell access__product"> <img class="access__logo" src="/static/logos/shipstation-api-logo.svg" alt="ShipStation API Logo" loading="lazy" decoding="async"/> <div class="access__sub">Formerly ShipEngine</div> </td> <td class="access__table-cell access__plans"> <a href="/apis/@shipstation-v2/docs/getting-started/plans/shipstation-api-free.md" class="access__plan">Free</a> <a href="/apis/@shipstation-v2/docs/getting-started/plans/shipstation-api-advanced-enterprise.md" class="access__plan">Advanced</a> <a href="/apis/@shipstation-v2/docs/getting-started/plans/shipstation-api-advanced-enterprise.md" class="access__plan">Enterprise</a> </td> </tr> <tr> <td class="access__table-cell"> <img class="access__logo" src="/static/logos/shipstation-logo.svg" alt="ShipStation Logo" loading="lazy" decoding="async"/> </td> <td class="access__table-cell access__plans"> <a href="/apis/@shipstation-v2/docs/getting-started/plans/shipstation-free-starter.md" class="access__plan access__plan--off">Free</a> <a href="/apis/@shipstation-v2/docs/getting-started/plans/shipstation-free-starter.md" class="access__plan access__plan--off">Starter</a> <a href="/apis/@shipstation-v2/docs/getting-started/plans/shipstation-standard-premium.md" class="access__plan">Standard</a> <a href="/apis/@shipstation-v2/docs/getting-started/plans/shipstation-standard-premium.md" class="access__plan">Premium</a> </td> </tr> </tbody> </table> <footer class="access__footer"> <a class="access__help" href="/apis/@shipstation-v2/docs/getting-started/products-and-plans.md"> Learn about products and plans <img src="/static/icons/external-link.svg" alt="External Link Icon" style="width: 16px;" loading="lazy" decoding="async"/> </a> </footer> </aside>Get list of Shipments
get/v2/shipments
Query parameters
shipment_status'pending' | 'processing' | 'label_purchased' | 'cancelled'
The possible shipment status values
batch_idstring
A string that uniquely identifies a ShipStation resource, such as a carrier, label, shipment, etc.
Example:se-28529731
Batch ID
tagstring
Tags are arbitrary strings that you can use to categorize shipments. For example, you may want to use tags to distinguish between domestic and international shipments, or between insured and uninsured shipments. Or maybe you want to create a tag for each of your customers so you can easily retrieve every shipment for a customer.
Example:Fragile
created_at_startstring date-time
Used to create a filter for when a resource was created (ex. A shipment that was created after a certain time)
created_at_endstring date-time
Used to create a filter for when a resource was created, (ex. A shipment that was created before a certain time)
modified_at_startstring date-time
Used to create a filter for when a resource was modified (ex. A shipment that was modified after a certain time)
modified_at_endstring date-time
Used to create a filter for when a resource was modified (ex. A shipment that was modified before a certain time)
pageinteger
Return a specific page of results. Defaults to the first page. If set to a number that's greater than the number of pages of results, an empty page is returned.
page_sizeinteger
The number of results to return per response.
sales_order_idstring
Sales Order ID
sort_dir'asc' | 'desc'
Controls the sort order of queries
| Value | Description |
|---|---|
| asc | Return results in ascending order |
| desc | Return results in descending order |
Controls the sort order of the query.
shipment_numberstring
The user or order source defined shipment number
ship_to_namestring
The name associated with the ship_to
item_keywordstring
Returns shipments that contain items that match the specified keyword. Fields searched are Sku, Description, and Options.
payment_date_startstring date-time
Used to create a filter for resources based on the payment_date parameter after a certain time.
payment_date_endstring date-time
Used to create a filter for resources based on the payment_date parameter before a certain time.
store_idstring
A string that uniquely identifies a ShipStation resource, such as a carrier, label, shipment, etc.
Example:se-28529731
Store ID
external_shipment_idstring
Filter labels by external shipment ID.
sort_by'modified_at' | 'created_at'
The possible shipments sort by values
Response
The request was a success.
Example response
{
"shipments": [
{
"shipment_id": "se-28529731",
"carrier_id": "se-28529731",
"service_code": "usps_first_class_mail",
"requested_shipment_service": "usps_priority_mail",
"external_order_id": "1232434",
"hold_until_date": "2025-01-15T00:00:00.000Z",
"ship_by_date": "2025-01-15T00:00:00.000Z",
"deliver_by_date": "2025-01-20T00:00:00.000Z",
"retail_rate": {
"amount": 12
},
"store_id": "se-28529731",
"items": [
{
"name": "box",
"sales_order_id": "12345",
"sales_order_item_id": "1234556",
"quantity": 1,
"sku": "sku-1234",
"bundle_sku": "bundle-123",
"external_order_id": "123445",
"external_order_item_id": "12",
"asin": "B00005N5PF",
"item_id": "1402291169813",
"allocation_status": "allocated",
"image_url": "https://example.com/image.jpg",
"weight": {
"value": 23
},
"unit_price": 88,
"tax_amount": 5.5,
"shipping_amount": 10,
"inventory_location": "warehouse-a",
"options": [
{
"name": "Color",
"value": "Red"
}
],
"product_id": "10408926",
"fullfilment_sku": "fulfill-123",
"upc": "123456789012"
}
],
"notes_from_buyer": "Please handle with care",
"notes_to_buyer": "Thank you for your order!",
"notes_for_gift": "Happy Birthday!",
"internal_notes": "Check packaging before shipping",
"is_gift": true,
"assigned_user": "user@example.com",
"amount_paid": {
"amount": 12
},
"shipping_paid": {
"amount": 12
},
"tax_paid": {
"amount": 12
},
"zone": 1,
"display_scheme": "label",
"tax_identifiers": [
{
"issuing_authority": "US",
"value": "value"
}
],
"external_shipment_id": "1234556",
"shipment_number": "10001",
"ship_date": "2018-09-23T00:00:00Z",
"created_at": "2018-09-23T15:00:00.000Z",
"modified_at": "2018-09-23T15:00:00.000Z",
"ship_to": {
"name": "John Doe",
"phone": "+1 204-253-9411 ext. 123",
"email": "example@example.com",
"company_name": "The Home Depot",
"address_line1": "1999 Bishop Grandin Blvd.",
"address_line2": "Unit 408",
"address_line3": "Building #7",
"city_locality": "Winnipeg",
"state_province": "Manitoba",
"postal_code": "78756-3717",
"country_code": "CA",
"instructions": "any instruction",
"geolocation": [
{
"type": "what3words",
"value": "cats.with.thumbs"
}
]
},
"ship_from": {
"name": "John Doe",
"phone": "+1 204-253-9411 ext. 123",
"email": "example@example.com",
"company_name": "The Home Depot",
"address_line1": "1999 Bishop Grandin Blvd.",
"address_line2": "Unit 408",
"address_line3": "Building #7",
"city_locality": "Winnipeg",
"state_province": "Manitoba",
"postal_code": "78756-3717",
"country_code": "CA",
"instructions": "any instructions",
"geolocation": [
{
"type": "what3words",
"value": "cats.with.thumbs"
}
]
},
"warehouse_id": "se-28529731",
"return_to": {
"name": "John Doe",
"phone": "+1 204-253-9411 ext. 123",
"email": "example@example.com",
"company_name": "The Home Depot",
"address_line1": "1999 Bishop Grandin Blvd.",
"address_line2": "Unit 408",
"address_line3": "Building #7",
"city_locality": "Winnipeg",
"state_province": "Manitoba",
"postal_code": "78756-3717",
"country_code": "CA",
"instructions": "any instructions",
"geolocation": [
{
"type": "what3words",
"value": "cats.with.thumbs"
}
]
},
"is_return": true,
"customs": {
"terms_of_trade_code": "ddp",
"contents": "gift",
"non_delivery": "return_to_sender"
},
"advanced_options": {
"bill_to_account": "123456789",
"bill_to_country_code": "CA",
"bill_to_postal_code": "28005",
"contains_alcohol": true,
"delivered_duty_paid": true,
"dry_ice": true,
"dry_ice_weight": {
"value": 23
},
"non_machinable": true,
"saturday_delivery": true,
"fedex_freight": {
"shipper_load_and_count": "shipper_load_and_count",
"booking_confirmation": "today"
},
"use_ups_ground_freight_pricing": true,
"freight_class": "77.5",
"custom_field1": "custom field 1",
"custom_field2": "custom field 2",
"custom_field3": "custom field 3",
"additional_handling": true,
"shipper_release": true,
"collect_on_delivery": {
"payment_amount": {
"amount": 12
}
},
"third_party_consignee": true,
"dangerous_goods": true,
"dangerous_goods_contact": {
"name": "Michael Robinson",
"phone": "123456578789"
},
"movement_indicator": "b2b",
"windsor_framework_details": {
"movement_indicator": "b2b",
"not_at_risk": true
},
"ancillary_endorsements_option": "forward",
"return_pickup_attempts": 3,
"netstamps_options": {
"row": 1,
"column": 1
}
},
"tags": [
{
"name": "Fragile"
}
],
"packages": [
{
"shipment_package_id": "se-28529731",
"package_id": "se-28529731",
"package_code": "small_flat_rate_box",
"package_name": "Flat Rate Envelope",
"weight": {
"value": 23
},
"dimensions": {
"length": 2,
"width": 2,
"height": 1
},
"insured_value": {
"amount": 12
},
"label_messages": {
"reference1": "Reference",
"reference2": "Reference 2",
"reference3": "Reference 3"
},
"external_package_id": "se-1234545",
"content_description": "Hand knitted wool socks",
"products": [
{
"description": "a minimum description",
"quantity": 1,
"value": {
"amount": 12
},
"weight": {
"value": 23
},
"harmonized_tariff_code": "3926.10",
"country_of_origin": "CA",
"unit_of_measure": "pound",
"sku": "sku-1223344",
"sku_description": "this is a description",
"mid_code": "GBCOM15BRI",
"product_url": "https://myproduct.com",
"vat_rate": 0.2,
"dangerous_goods": [
{
"id_number": "1234r1",
"shipping_name": "things with dangerous goods",
"technical_name": "chloric acid",
"product_class": "1987",
"product_class_subsidiary": "1987",
"packaging_group": "ii",
"dangerous_amount": {
"amount": 12,
"unit": "GBP"
},
"quantity": 1,
"packaging_instruction": "Packaging materials and containers that are in contact with food products must comply with the provisions established by Regulation ",
"packaging_instruction_section": "section_1",
"packaging_type": "X",
"transport_mean": "ground",
"transport_category": "6.1",
"regulation_authority": "AEAT",
"regulation_level": "excepted_quantity",
"tunnel_code": "all",
"additional_description": "any description"
}
],
"manufacturer_product_id": "012345678905",
"manufacturer_ns_product_id": "MY-SKU-12345",
"cpsc_certificates": [
{
"certifier_id": "CERT-12345",
"certificate_version_id": "v1.0"
}
]
}
]
}
],
"total_weight": {
"value": 3
},
"comparison_rate_type": "retail"
}
],
"total": 1990,
"page": 12,
"pages": 4,
"links": {
"first": {
"href": "https://example.com/resource",
"type": "child"
},
"last": {
"href": "https://example.com/resource",
"type": "child"
},
"prev": {
"href": "https://example.com/resource",
"type": "child"
},
"next": {
"href": "https://example.com/resource",
"type": "child"
}
}
}