{"templateId":"markdown","versions":[{"version":"shipengine","label":"ShipStation API (formerly ShipEngine)","link":"/apis/shipengine/docs/orders/understanding-orders-shipments","default":false,"active":false,"folderId":"58c9a61d"},{"version":"shipstation-v2","label":"ShipStation V2 API","link":"/apis/docs/orders/understanding-orders-shipments","default":true,"active":true,"folderId":"58c9a61d"},{"version":"shipstation-v1","label":"ShipStation V1 API","link":"/apis/shipstation-v1/docs/orders/understanding-orders-shipments","default":false,"active":false,"folderId":"58c9a61d"}],"sharedDataIds":{"sidebar":"sidebar-apis/@shipengine/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Understanding Orders & Shipments","keywords":"shipping, labels, shipstation, documentation, api","siteUrl":"https://docs.shipstation.com","lang":"en-US","llmstxt":{"hide":false,"title":"ShipStation API LLM Docs","description":"Find links and references to all markdown documentation for use with LLMs","excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"understanding-orders--shipments","__idx":0},"children":["Understanding Orders & Shipments"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In ShipStation API v2, what you might think of as an \"order\" is actually called a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["shipment"]},". This terminology shift can be confusing if you're coming from the ShipStation UI or the v1 Companion API, but it aligns with industry-standard shipping terminology."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"core-concepts","__idx":1},"children":["Core Concepts"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"what-is-a-shipment-in-v2","__idx":2},"children":["What is a Shipment in v2?"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["shipment"]}," in v2 represents the intent to ship something. It contains:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Ship-to and ship-from addresses"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Package dimensions and weight"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Items being shipped"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Carrier and service preferences"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Custom metadata and identifiers"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In the ShipStation UI and v1 API, this same concept was called an ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["order"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"what-is-a-label-in-v2","__idx":3},"children":["What is a Label in v2?"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["label"]}," in v2 represents a purchased shipping label from a carrier. It includes:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The actual label file (PDF, PNG, ZPL)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Tracking number"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Shipping cost"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Carrier details"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Associated shipment information"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In the ShipStation UI and v1 API, this was called a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["shipment"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"quick-reference-table","__idx":4},"children":["Quick Reference Table"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":""},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["ShipStation UI / v1 Term"]}]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":""},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["v2 API Term"]}]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":""},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["What It Represents"]}]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Order"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Shipment"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Intent to ship; order details and addresses"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["order_id"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["shipment_id"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Unique identifier for the shipment (with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["se-"]}," prefix)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["orderNumber"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["shipment_number"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["User-friendly reference number"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["orderKey"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["external_shipment_id"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Your system's identifier for the shipment"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Shipment"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Label"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Purchased shipping label from carrier"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["shipment_id"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["label_id"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Unique identifier for the label (with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["se-"]}," prefix)"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"why-the-terminology-changed","__idx":5},"children":["Why the Terminology Changed"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The v2 terminology aligns with how most shipping carriers and APIs describe these concepts:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Shipment"]}," = The shipping request/intent (what you're sending and where)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Label"]}," = The physical/digital artifact used to ship it"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This makes integration more intuitive for developers familiar with carrier APIs like UPS, FedEx, and USPS, and matches the terminology used by ShipEngine API."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"related-guides","__idx":6},"children":["Related Guides"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For detailed information about specific aspects of orders and shipments in v2:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/orders/external-identifiers"},"children":["External Identifiers Guide"]}]}," - Learn about ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["external_shipment_id"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["external_order_id"]},", and how they relate to v1 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["orderKey"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/orders/shipment-numbers"},"children":["Shipment Numbers & Uniqueness"]}]}," - Understand ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["shipment_number"]}," uniqueness rules and auto-population"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/orders/legacy-migration"},"children":["Legacy API Migration"]}]}," - Migration guidance for v1 users and legacy ShipStation UI behavior"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products-and-plans#api-version-terminology-reference"},"children":["Products and Plans - Terminology Reference"]}]}," - Complete v1 to v2 terminology mapping"]}]}]},"headings":[{"value":"Understanding Orders & Shipments","id":"understanding-orders--shipments","depth":1},{"value":"Core Concepts","id":"core-concepts","depth":2},{"value":"What is a Shipment in v2?","id":"what-is-a-shipment-in-v2","depth":3},{"value":"What is a Label in v2?","id":"what-is-a-label-in-v2","depth":3},{"value":"Quick Reference Table","id":"quick-reference-table","depth":2},{"value":"Why the Terminology Changed","id":"why-the-terminology-changed","depth":2},{"value":"Related Guides","id":"related-guides","depth":2}],"frontmatter":{"slug":"/orders/understanding-orders-shipments","seo":{"title":"Understanding Orders & Shipments"}},"lastModified":"2026-07-02T22:02:49.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/orders/understanding-orders-shipments","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}