shipments

List shipments

Changed on Oct 22, 2026

<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

Request

Base URL
https://api.shipstation.com
URL
https://api.shipstation.com/v2/shipments
Auth
API key in header api-key

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

Filter shipments by tag name. Returns only shipments that have been assigned the specified tag. You can filter by one tag at a time. Tags are arbitrary strings used to categorize shipments (e.g., "Priority", "Fragile", "International").

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.

totalinteger required

Total number of shipments returned by the api call

pageinteger required

pagesinteger required

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": "8c1f2a5e-3b7d-4e9a-a6c2-1d4f5e6a7b8c",
          "sales_order_item_id": "2e7b9c4d-6a1f-4c3e-8b5d-9f0a1b2c3d4e",
          "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
        },
        "suppress_carrier_generated_documents": [
          "commercial_invoice"
        ],
        "transparency_codes": [
          {
            "order_item_id": "12345678901234",
            "codes": [
              "AZ:XXXXXXXXXXXX"
            ]
          }
        ]
      },
      "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"
                }
              ],
              "cpsc_disclaim": {
                "disclaim_code": "B",
                "intended_use_code": "130.006"
              }
            }
          ]
        }
      ],
      "total_weight": {
        "value": 3
      },
      "batch_ids": [
        "se-9581628",
        "se-1935182"
      ],
      "comparison_rate_type": "retail",
      "sales_order_ids": [
        "8c1f2a5e-3b7d-4e9a-a6c2-1d4f5e6a7b8c"
      ]
    }
  ],
  "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"
    }
  }
}

Changes

Oct 22, 20264e29670aa28d Revision changes
- warning
  added the new bring_your_own_label_not_supported enum value to the // response property for the response status
- warning
  added the new bring_your_own_label_not_supported enum value to the // response property for the response status
- warning
  added the new multiple_sales_orders enum value to the // response property for the response status
- warning
  added the new multiple_sales_orders enum value to the // response property for the response status
- warning
  added the new sales_order_link_required enum value to the // response property for the response status
- warning
  added the new sales_order_link_required enum value to the // response property for the response status
- info
  added subschema #2: shipment_sales_order_fields to the // response property allOf list for the response status
Oct 16, 2026bf3618aaf7e1 Revision changes
- breaking
  the response property ////// became nullable for the status
- breaking
  the response property ////// became nullable for the status
- breaking
  the response property ////// became nullable for the status
- breaking
  the response property ////// became nullable for the status
- breaking
  the response property ////// became nullable for the status
- breaking
  the response property ////// became nullable for the status
- breaking
  the response property ////// became nullable for the status
- breaking
  the response property ////// became nullable for the status
- breaking
  the response property ////// became nullable for the status
- breaking
  the response property ////// became nullable for the status
- breaking
  the response property ////// became nullable for the status
- breaking
  the response property ////// became nullable for the status
- breaking
  the response property //// became nullable for the status
- breaking
  the response property //// became nullable for the status
- breaking
  the response property //// became nullable for the status
- breaking
  the response property //// became nullable for the status
- breaking
  the response property //// became nullable for the status
- breaking
  the response property //// became nullable for the status
- breaking
  the response property //// became nullable for the status
- breaking
  the response property //// became nullable for the status
- breaking
  the response property //// became nullable for the status
- breaking
  the response property ////// became nullable for the status
- breaking
  the response property ////// became nullable for the status
- breaking
  the response property ////// became nullable for the status
- breaking
  the response property ////// became nullable for the status
- breaking
  the response property ////// became nullable for the status
- breaking
  the response property ////// became nullable for the status
- breaking
  the response property ////// became nullable for the status
- breaking
  the response property ////// became nullable for the status
- breaking
  the response property ////// became nullable for the status
- breaking
  the response property ////// became nullable for the status
- breaking
  the response property ////// became nullable for the status
- breaking
  the response property ////// became nullable for the status
- breaking
  the response property ////// became nullable for the status
- breaking
  the response property ////// became nullable for the status
- breaking
  the response property ////// became nullable for the status
- breaking
  the response property ////// became nullable for the status
- breaking
  the response property ////// became nullable for the status
- breaking
  the response property //// became nullable for the status
- breaking
  the response property //// became nullable for the status
- breaking
  the response property //// became nullable for the status
- breaking
  the response property ////// became nullable for the status
- breaking
  the response property /////// became nullable for the status
- breaking
  the response property /////// became nullable for the status
- breaking
  the response property /////// became nullable for the status
- breaking
  the response property //////// became nullable for the status
- breaking
  the response property //////// became nullable for the status
- breaking
  the response property ///////// became nullable for the status
- breaking
  the response property ////////// became nullable for the status
- breaking
  the response property //////////// became nullable for the status
- breaking
  the response property ////////// became nullable for the status
- breaking
  the response property ////////// became nullable for the status
- breaking
  the response property ////////// became nullable for the status
- breaking
  the response property ////////// became nullable for the status
- breaking
  the response property ////////// became nullable for the status
- breaking
  the response property ////////// became nullable for the status
- breaking
  the response property ////////// became nullable for the status
- breaking
  the response property ////////// became nullable for the status
- breaking
  the response property ////////// became nullable for the status
- breaking
  the response property ////////// became nullable for the status
- breaking
  the response property ////////// became nullable for the status
- breaking
  the response property ////////// became nullable for the status
- breaking
  the response property //////// became nullable for the status
- breaking
  the response property //////// became nullable for the status
- breaking
  the response property //////// became nullable for the status
- breaking
  the response property //////// became nullable for the status
- breaking
  the response property //////// became nullable for the status
- breaking
  the response property //////// became nullable for the status
- breaking
  the response property //////// became nullable for the status
- breaking
  the response property //////// became nullable for the status
- breaking
  the response property //////// became nullable for the status
- breaking
  the response property //////// became nullable for the status
- breaking
  the response property //// became nullable for the status
- breaking
  the response property //////// became nullable for the status
- breaking
  the response property //////// became nullable for the status
- breaking
  the response property //////// became nullable for the status
- breaking
  the response property //////// became nullable for the status
- breaking
  the response property /////// became nullable for the status
- breaking
  the response property //// became nullable for the status
- breaking
  the response property //////// became nullable for the status
- breaking
  the response property //////// became nullable for the status
- breaking
  the response property //////// became nullable for the status
- breaking
  the response property //////// became nullable for the status
- breaking
  the response property /////// became nullable for the status
- breaking
  the response property //////// became nullable for the status
- breaking
  the response property //////// became nullable for the status
- breaking
  the response property //////// became nullable for the status
- breaking
  the response property //////// became nullable for the status
- breaking
  the response property /////// became nullable for the status
- breaking
  the response property //// became nullable for the status
- breaking
  the response property //// became nullable for the status
- breaking
  the response property //// became nullable for the status
- breaking
  added subschema #2 to the ////// response property oneOf list for the response status
- breaking
  added subschema #2 to the ////// response property oneOf list for the response status
- breaking
  added subschema #2 to the //////// response property oneOf list for the response status
- breaking
  added subschema #2 to the //// response property oneOf list for the response status
- breaking
  added subschema #2 to the //// response property oneOf list for the response status
- breaking
  added subschema #2 to the //////// response property oneOf list for the response status
- breaking
  added subschema #2 to the //// response property oneOf list for the response status
- breaking
  added subschema #2 to the ////// response property oneOf list for the response status
- breaking
  added subschema #2 to the ////// response property oneOf list for the response status
- breaking
  added subschema #2 to the //// response property oneOf list for the response status
- breaking
  added subschema #2 to the //// response property oneOf list for the response status
- breaking
  added subschema #2 to the //// response property oneOf list for the response status
- breaking
  added subschema #2 to the ////// response property oneOf list for the response status
- breaking
  the //////// response's property type changed from string to no type for status
- info
  removed from the ////// response property allOf list for the response status
- info
  removed from the ////// response property allOf list for the response status
- info
  removed from the //////// response property allOf list for the response status
- info
  removed from the //// response property allOf list for the response status
- info
  removed from the //// response property allOf list for the response status
- info
  removed from the //////// response property allOf list for the response status
- info
  removed from the //// response property allOf list for the response status
- info
  removed from the ////// response property allOf list for the response status
- info
  removed from the ////// response property allOf list for the response status
- info
  removed from the //// response property allOf list for the response status
- info
  removed from the //// response property allOf list for the response status
- info
  removed from the //// response property allOf list for the response status
- info
  removed from the ////// response property allOf list for the response status

Operation history (11 revisions)