latestOpenAPI 3.1.0MIT2026-08-221643491.4 MB

d3d8c21cd227

shipments

Get shipment by id

<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 an individual shipment based on its ID

get/v2/shipments/{shipment_id}

Response

The request was a success.

shipment_idstring

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

carrier_idstring

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

service_codestring

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

requested_shipment_servicestring

The requested shipment service

external_order_idstring

ID that the Order Source assigned

hold_until_datestring date-time

Date to hold the shipment until

ship_by_datestring date-time

Date by which the shipment should be shipped

deliver_by_datestring date-time

Date by which the shipment should be delivered

store_idstring

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

notes_from_buyerstring

Notes from the buyer

notes_to_buyerstring

Notes to the buyer

notes_for_giftstring

Gift notes

internal_notesstring

Internal notes from the seller

is_giftboolean

Indicates if the shipment is a gift

assigned_userstring

User assigned to the shipment

zoneinteger

Shipping zone

display_schemestring

Display scheme for the shipment

external_shipment_idstring

A user-defined key that identifies the source order. Multiple shipments can share the same external_shipment_id (common in split-shipping scenarios where one order results in multiple shipments). Functionally identical to orderKey in V1 API.

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

shipment_numberstring

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

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 ShipStation .

created_atstring date-time

An ISO 8601 string that represents a date and time.

modified_atstring date-time

An ISO 8601 string that represents a date and time.

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

The possible shipment status values

warehouse_idstring

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

is_returnboolean

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

confirmation'none' | 'delivery' | 'signature' | 'adult_signature' | 'adult_signature_restricted_delivery' | 'direct_signature' | 'delivery_mailed' | 'verbal_confirmation' | 'delivery_code' | 'age_verification_16_plus'

The possible delivery confirmation values

insurance_provider'none' | 'shipsurance' | 'parcelguard' | 'xcover' | 'carrier' | 'third_party'

The possible insurance provider values

order_source_code'amazon_ca' | 'amazon_us' | 'brightpearl' | 'channel_advisor' | 'cratejoy' | 'ebay' | 'etsy' | 'jane' | 'groupon_goods' | 'magento' | 'paypal' | 'seller_active' | 'shopify' | 'stitch_labs' | 'squarespace' | 'three_dcart' | 'tophatter' | 'walmart' | 'woo_commerce' | 'volusion'

The order sources that are supported by ShipStation

comparison_rate_typestring

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

Example response

{
  "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"
}