shipments

Get shipment by external ID

Changed on Oct 22, 2026

Query Shipments created using your own custom ID convention using this endpint

get/v1/shipments/external_shipment_id/{external_shipment_id}

Request

Base URL: https://api.shipengine.com
URL: https://api.shipengine.com/v1/shipments/external_shipment_id/{external_shipment_id}
Auth: API key in header API-Key

Response

The request was a success.

shipment_idstring required

A string that uniquely identifies a ShipEngine resource, such as a carrier, label, shipment, etc.

carrier_idstring required

A string that uniquely identifies a ShipEngine resource, such as a carrier, label, shipment, etc.

service_codestring required

A carrier service, such as fedex_ground, usps_first_class_mail, flat_rate_envelope, etc.

shipping_rule_idstring

A string that uniquely identifies a ShipEngine resource, such as a carrier, label, shipment, etc.

external_order_idstring nullable

ID that the Order Source assigned

external_shipment_idstring nullable

A unique user-defined key to identify a shipment. This can be used to retrieve the shipment.

Warning: The external_shipment_id is limited to 50 characters. Any additional characters will be truncated.

shipment_numberstring nullable

A non-unique user-defined number used to identify a shipment. If undefined, this will match the external_shipment_id of the shipment.

Warning: The shipment_number is limited to 50 characters. Any additional characters will be truncated.

ship_datestring date-time required

An ISO 8601 string that represents a date, but not a specific time. The value may contain a time component, but it will be set to 00:00:00 UTC by ShipEngine.

created_atstring date-time required

An ISO 8601 string that represents a date and time.

modified_atstring date-time required

An ISO 8601 string that represents a date and time.

shipment_status'pending' | 'processing' | 'label_purchased' | 'cancelled' required

The possible shipment status values

warehouse_idstring required

A string that uniquely identifies a ShipEngine resource, such as a carrier, label, shipment, etc.

is_returnboolean nullable

An optional indicator if the shipment is intended to be a return. Defaults to false if not provided.

The possible delivery confirmation values

The possible insurance provider values

The order sources that are supported by ShipEngine

batch_idsSeId[] required

The unique IDs of any batches that this shipment is associated with. Returns an empty array if the shipment isn't associated with any batch.

If the shipment is associated with more than one batch, the IDs are ordered by batch status priority: open, queued, processing, completed, completed_with_errors, archived, notifying, then invalid.

comparison_rate_typestring nullable

Calculate a rate for this shipment with the requested carrier using a ratecard that differs from the default. Only supported for UPS and USPS.

zoneinteger nullable

Certain carriers base their rates off of custom zones that vary depending upon the ship_to and ship_from location

sales_order_idsstring[]

The IDs of the sales orders that the shipment is linked to. The array is empty if the shipment isn't linked to a sales order. This field is read-only and is ignored in requests.

A shipment must be linked to a sales order before it can be split or merged.

Note: After a split, the original shipment can still list a sales order even if all of that sales order's items have moved to other shipments. To see which sales order each item belongs to, use items[].sales_order_id.

Example response

{
  "shipment_id": "se-28529731",
  "carrier_id": "se-28529731",
  "service_code": "usps_first_class_mail",
  "shipping_rule_id": "se-28529731",
  "items": [
    {
      "sales_order_id": "8c1f2a5e-3b7d-4e9a-a6c2-1d4f5e6a7b8c",
      "sales_order_item_id": "2e7b9c4d-6a1f-4c3e-8b5d-9f0a1b2c3d4e",
      "asin": "B00005N5PF",
      "item_id": "1402291169813"
    }
  ],
  "ship_date": "2018-09-23T00:00:00.000Z",
  "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",
    "address_residential_indicator": "no",
    "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",
    "address_residential_indicator": "no",
    "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",
    "address_residential_indicator": "no",
    "geolocation": [
      {
        "type": "what3words",
        "value": "cats.with.thumbs"
      }
    ]
  },
  "customs": {
    "terms_of_trade_code": "ddp",
    "contents": "gift",
    "non_delivery": "return_to_sender"
  },
  "advanced_options": {
    "bill_to_country_code": "CA",
    "freight_class": "77.5",
    "collect_on_delivery": {
      "payment_amount": {
        "currency": "USD"
      }
    },
    "movement_indicator": "c2c",
    "license_number": "514785",
    "invoice_number": "IOC56888",
    "certificate_number": "784515",
    "fragile": true,
    "delivery_as_addressed": true,
    "return_after_first_attempt": true,
    "netstamps_options": {
      "row": 1,
      "column": 1
    },
    "suppress_carrier_generated_documents": [
      "commercial_invoice"
    ],
    "transparency_codes": [
      {
        "order_item_id": "12345678901234",
        "codes": [
          "AZ:XXXXXXXXXXXX"
        ]
      }
    ]
  },
  "tags": [
    {
      "tag_id": 8712,
      "name": "Fragile",
      "color": "#FF0000"
    }
  ],
  "packages": [
    {
      "shipment_package_id": "se-28529731",
      "package_id": "se-28529731",
      "package_code": "small_flat_rate_box",
      "insured_value": {
        "currency": "USD"
      },
      "content_description": "Hand knitted wool socks",
      "products": [
        {
          "value": {
            "currency": "USD"
          },
          "harmonized_tariff_code": "3926.1",
          "country_of_origin": "CA",
          "vat_rate": 0.2,
          "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"
          }
        }
      ]
    }
  ],
  "batch_ids": [
    "se-9581628",
    "se-1935182"
  ],
  "comparison_rate_type": "retail",
  "zone": 6,
  "sales_order_ids": [
    "8c1f2a5e-3b7d-4e9a-a6c2-1d4f5e6a7b8c"
  ]
}

Changes

Oct 22, 2026e998dffc42be 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 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 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
- warning
  added the new sales_order_link_required enum value to the // response property for the response status
- info
  added the optional property //// to the response with the status
- info
  added subschema #2: shipment_sales_order_fields to the response property allOf list for the response status
Oct 9, 2026020f57d6f5b8 Revision changes
- breaking
  the ////// response's property type changed from no type to string for status
- breaking
  the ///// response's property type changed from no type to string for status
- breaking
  the ////// response's property type changed from no type to string for status
- breaking
  the /// response's property type changed from no type to string for status
- breaking
  the //////// response's property type changed from no type to string for status
- breaking
  the //// response's property type changed from no type to object for status
- breaking
  the //// response's property type changed from no type to object for status
- breaking
  the /// response's property type changed from no type to object for status
- breaking
  the // response's property type changed from no type to string for status
- breaking
  the /// response's property type changed from no type to object for status
- breaking
  the ////// response's property type changed from no type to string for status
- breaking
  the ////// response's property type changed from no type to string for status
- breaking
  the ////// response's property type changed from no type to string for status
- breaking
  the /// response's property type changed from no type to object for status
- breaking
  the /// response's property type changed from no type to object for status
- breaking
  the //// response's property type changed from no type to string for status
- breaking
  the / response's property type changed from no type to object for status
- breaking
  the / response's property type changed from no type to object for status
- breaking
  the / response's property type changed from no type to object for status
- warning
  added the new amazon_ca enum value to the // response property for the response status
- warning
  added the new amazon_us enum value to the // response property for the response status
- warning
  added the new any enum value to the ///// response property for the response status
- warning
  added the new brightpearl enum value to the // response property for the response status
- warning
  added the new cash enum value to the ///// response property for the response status
- warning
  added the new cash_equivalent enum value to the ///// response property for the response status
- warning
  added the new channel_advisor enum value to the // response property for the response status
- warning
  added the new cratejoy enum value to the // response property for the response status
- warning
  added the new ebay enum value to the // response property for the response status
- warning
  added the new etsy enum value to the // response property for the response status
- warning
  added the new gram enum value to the ////// response property for the response status
- warning
  added the new gram enum value to the //////// response property for the response status
- warning
  added the new gram enum value to the //// response property for the response status
- warning
  added the new groupon_goods enum value to the // response property for the response status
- warning
  added the new jane enum value to the // response property for the response status
- warning
  added the new kilogram enum value to the ////// response property for the response status
- warning
  added the new kilogram enum value to the //////// response property for the response status
- warning
  added the new kilogram enum value to the //// response property for the response status
- warning
  added the new magento enum value to the // response property for the response status
- warning
  added the new none enum value to the ///// response property for the response status
- warning
  added the new ounce enum value to the ////// response property for the response status
- warning
  added the new ounce enum value to the //////// response property for the response status
- warning
  added the new ounce enum value to the //// response property for the response status
- warning
  added the new paypal enum value to the // response property for the response status
- warning
  added the new pound enum value to the ////// response property for the response status
- warning
  added the new pound enum value to the //////// response property for the response status
- warning
  added the new pound enum value to the //// response property for the response status
- warning
  added the new seller_active enum value to the // response property for the response status
- warning
  added the new shopify enum value to the // response property for the response status
- warning
  added the new squarespace enum value to the // response property for the response status
- warning
  added the new stitch_labs enum value to the // response property for the response status
- warning
  added the new three_dcart enum value to the // response property for the response status
- warning
  added the new tophatter enum value to the // response property for the response status
- warning
  added the new volusion enum value to the // response property for the response status
- warning
  added the new walmart enum value to the // response property for the response status
- warning
  added the new woo_commerce enum value to the // response property for the response status
- info
  added the optional property ///// to the response with the status
- info
  added the optional property ///// to the response with the status
- info
  added the optional property ///// to the response with the status
- info
  added the optional property ///// to the response with the status
- info
  added the optional property ///// to the response with the status
- info
  added the optional property ///// to the response with the status
- info
  added the optional property ///// to the response with the status
- info
  added the optional property ///// to the response with the status
- info
  added the optional property ///// to the response with the status
- info
  added the optional property ///// to the response with the status
- info
  added the optional property ///// to the response with the status
- info
  added the optional property ///// to the response with the status
- info
  added the optional property ///// to the response with the status
- info
  added the optional property //// to the response with the status
- info
  added the optional property //// to the response with the status
- info
  added the optional property //// to the response with the status
- info
  added the optional property //// to the response with the status
- info
  added the optional property //// to the response with the status
- info
  added the optional property //// to the response with the status
- info
  added the optional property //// to the response with the status
- info
  added the optional property //// to the response with the status
- info
  added the optional property //// to the response with the status
- info
  added the optional property //// to the response with the status
- info
  added the optional property //// to the response with the status
- info
  added the optional property //// to the response with the status
- info
  added the optional property //// to the response with the status
- info
  added the optional property //// to the response with the status
- info
  added the optional property //// to the response with the status
- info
  added the optional property //// to the response with the status
- info
  added the optional property //// to the response with the status
- info
  added the optional property //// to the response with the status
- info
  added the optional property //// to the response with the status
- info
  added the optional property //// to the response with the status
- info
  added the optional property //// to the response with the status
- info
  added the optional property //// to the response with the status
- info
  added the optional property // to the response with the status
- info
  added the optional property // to the response with the status
- info
  added the optional property // to the response with the status
- info
  added the optional property // to the response with the status
- info
  added the optional property // to the response with the status
- info
  added the optional property // to the response with the status
- info
  added the optional property // to the response with the status
- info
  added the optional property // to the response with the status
- info
  added the optional property // to the response with the 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
- 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
  the /// response's property pattern ^se(-[a-z0-9]+)+$ was added for the status
- info
  added the required property ///// to the response with the status
- info
  added the required property ///// to the response with the status
- info
  added the required property ///// to the response with the status
- info
  added the required property ///// to the response with the status
- info
  added the required property ///// to the response with the status
- info
  added the required property //// to the response with the status
- info
  added the required property //// to the response with the status
- info
  added the required property //// to the response with the status
- info
  added the required property //// to the response with the status
- info
  added the required property //// to the response with the status
- info
  added the required property //// to the response with the status
- info
  added the required property // to the response with the status
- info
  added the required property // to the response with the status
- info
  added the required property // to the response with the status
- info
  added the required property // to the response with the status
- info
  added the required property // to the response with the status
- info
  added the required property // to the response with the status
- info
  added the required property // to the response with the status
- info
  added the required property // to the response with the status
- info
  added the required property // to the response with the status
- info
  added the required property // to the response with the status
- info
  added the required property // to the response with the status
- info
  added the required property // to the response with the status

Operation history (9 revisions)