{"templateId":"markdown","versions":[{"version":"shipengine","label":"ShipStation API (formerly ShipEngine)","link":"/apis/shipengine/docs/orders/external-identifiers","default":false,"active":false,"folderId":"58c9a61d"},{"version":"shipstation-v2","label":"ShipStation V2 API","link":"/apis/docs/orders/external-identifiers","default":true,"active":true,"folderId":"58c9a61d"},{"version":"shipstation-v1","label":"ShipStation V1 API","link":"/apis/shipstation-v1/docs/orders/external-identifiers","default":false,"active":false,"folderId":"58c9a61d"}],"sharedDataIds":{"sidebar":"sidebar-apis/@shipengine/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"type":"markdown"},"seo":{"title":"External Identifiers Guide","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":"external-identifiers-guide","__idx":0},"children":["External Identifiers Guide"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["ShipStation API v2 uses external identifiers to link shipments and labels to records in your own system. Understanding how these identifiers work is crucial for integration."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"external_shipment_id","__idx":1},"children":["external_shipment_id"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["external_shipment_id"]}," is ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["your system's unique identifier"]}," for a shipment. This field serves the same purpose as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["orderKey"]}," in the v1 API."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"key-characteristics","__idx":2},"children":["Key Characteristics"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["User-defined"]},": You set this value when creating a shipment"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Optional but recommended"]},": Not required, but strongly recommended for tracking"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Must be unique"]},": Each ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["external_shipment_id"]}," must be unique per account"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Immutable"]},": Cannot be changed after shipment creation"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Exists at two levels"]},": Both shipments and labels have this field"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"v1-to-v2-mapping","__idx":3},"children":["v1 to v2 Mapping"]},{"$$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":["v1 Property"]}]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":""},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["v2 Property"]}]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":""},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Notes"]}]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$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":["Same concept, different name"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Example:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"external_shipment_id\": \"ORDER-2024-12345\",\n  \"ship_to\": { ... },\n  \"ship_from\": { ... }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"automatic-population","__idx":4},"children":["Automatic Population"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["do not provide"]}," an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["external_shipment_id"]}," when creating a shipment, the API will automatically generate one based on the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["shipment_id"]},":"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Provided: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"external_shipment_id\": \"MY-ORDER-123\""]}," → Uses your value"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Not provided: System generates → ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"external_shipment_id\": \"se-123456789\""]}]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"success","name":"Best Practice"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Always provide your own ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["external_shipment_id"]}," when creating shipments. This makes it much easier to correlate ShipStation records with your own system's orders."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"external_order_id","__idx":5},"children":["external_order_id"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["external_order_id"]}," is a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["read/write field"]}," that represents the ID of an order record in the ShipStation UI system (if one exists)."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"key-characteristics-1","__idx":6},"children":["Key Characteristics"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["System-populated by default"]},": When a shipment is created through certain flows, ShipStation may automatically populate this"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Now user-settable"]},": As of recent updates, you can set this value when creating shipments"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Optional"]},": Not required for API-only workflows"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Different from external_shipment_id"]},": These are two separate concepts"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"what-sets-external_order_id","__idx":7},"children":["What Sets external_order_id?"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["external_order_id"]}," can be populated in several ways:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Automatically"]}," - When a shipment is imported from a connected sales channel (e.g., Shopify, Amazon)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["By the system"]}," - When using legacy ShipStation UI v2 features"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["By you"]}," - You can now explicitly set this value when creating shipments via API"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"when-do-you-need-it","__idx":8},"children":["When Do You Need It?"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Most API-only integrations ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["do not need"]}," to use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["external_order_id"]},". Use it when:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["You're integrating with the ShipStation UI and need to link API-created shipments to UI orders"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["You're migrating from legacy systems that used this field"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["You need to track which ShipStation UI order a shipment originated from"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Example:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"external_shipment_id\": \"MY-ORDER-123\",\n  \"external_order_id\": \"SS-ORDER-456\",\n  \"ship_to\": { ... }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"API-Only Workflows"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you're building a pure API integration (no ShipStation UI involvement), you typically only need ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["external_shipment_id"]},". The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["external_order_id"]}," is primarily useful for UI integrations."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"shipment-level-vs-label-level-external_shipment_id","__idx":9},"children":["Shipment-Level vs Label-Level external_shipment_id"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Both ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["shipments"]}," and ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["labels"]}," have an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["external_shipment_id"]}," field, and they're closely related:"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"how-theyre-connected","__idx":10},"children":["How They're Connected"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["When you create a shipment"]},", you provide ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["external_shipment_id"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["When you create a label from that shipment"]},", the label inherits the shipment's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["external_shipment_id"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Both records share the same value"]},", making it easy to link labels back to your original order"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Example Flow:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"1. Create Shipment\n   POST /v2/shipments\n   {\n     \"external_shipment_id\": \"ORDER-2024-12345\",\n     ...\n   }\n   Response: { \"shipment_id\": \"se-123456\" }\n\n2. Create Label from Shipment\n   POST /v2/labels/shipment/se-123456\n   \n   Label Response includes:\n   {\n     \"label_id\": \"se-789012\",\n     \"shipment_id\": \"se-123456\",\n     \"external_shipment_id\": \"ORDER-2024-12345\"  ← Inherited from shipment\n   }\n"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"querying-by-external_shipment_id","__idx":11},"children":["Querying by external_shipment_id"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can retrieve records using ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["external_shipment_id"]},":"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"GET /v2/labels/external_shipment_id/ORDER-2024-12345\nGET /v2/shipments/external_shipment_id/ORDER-2024-12345\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This makes it easy to find ShipStation records using your own system's identifiers."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"best-practices","__idx":12},"children":["Best Practices"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"always-use-your-own-ids","__idx":13},"children":["Always Use Your Own IDs"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"// ✅ Good - Provide your own external_shipment_id\n{\n  \"external_shipment_id\": \"SHOPIFY-ORDER-98765\",\n  \"ship_to\": { ... }\n}\n\n// ❌ Not ideal - Relying on auto-generated IDs\n{\n  // No external_shipment_id provided\n  // System will use \"se-123456789\"\n  \"ship_to\": { ... }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"use-consistent-naming","__idx":14},"children":["Use Consistent Naming"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Choose a naming pattern and stick with it:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ORDER-{id}"]}," (e.g., ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ORDER-12345"]},")"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{source}-{id}"]}," (e.g., ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SHOPIFY-98765"]},")"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{prefix}-{date}-{id}"]}," (e.g., ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["WEB-20240615-001"]},")"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"dont-confuse-the-two","__idx":15},"children":["Don't Confuse the Two"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"external_shipment_id\": \"MY-ORDER-123\",    // Your order ID\n  \"external_order_id\": \"SS-UI-ORDER-456\",    // ShipStation UI order ID (if applicable)\n  \"shipment_id\": \"se-789012\"                  // ShipStation's internal ID (read-only)\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"related-guides","__idx":16},"children":["Related Guides"]},{"$$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/understanding-orders-shipments"},"children":["Understanding Orders & Shipments"]}]}," - Core concepts overview"]},{"$$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"]}]}," - Learn about ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["shipment_number"]}]},{"$$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"]}]}," - Migrating from v1 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["orderKey"]}]}]}]},"headings":[{"value":"External Identifiers Guide","id":"external-identifiers-guide","depth":1},{"value":"external_shipment_id","id":"external_shipment_id","depth":2},{"value":"Key Characteristics","id":"key-characteristics","depth":3},{"value":"v1 to v2 Mapping","id":"v1-to-v2-mapping","depth":3},{"value":"Automatic Population","id":"automatic-population","depth":3},{"value":"external_order_id","id":"external_order_id","depth":2},{"value":"Key Characteristics","id":"key-characteristics-1","depth":3},{"value":"What Sets external_order_id?","id":"what-sets-external_order_id","depth":3},{"value":"When Do You Need It?","id":"when-do-you-need-it","depth":3},{"value":"Shipment-Level vs Label-Level external_shipment_id","id":"shipment-level-vs-label-level-external_shipment_id","depth":2},{"value":"How They're Connected","id":"how-theyre-connected","depth":3},{"value":"Querying by external_shipment_id","id":"querying-by-external_shipment_id","depth":3},{"value":"Best Practices","id":"best-practices","depth":2},{"value":"Always Use Your Own IDs","id":"always-use-your-own-ids","depth":3},{"value":"Use Consistent Naming","id":"use-consistent-naming","depth":3},{"value":"Don't Confuse the Two","id":"dont-confuse-the-two","depth":3},{"value":"Related Guides","id":"related-guides","depth":2}],"frontmatter":{"slug":"/orders/external-identifiers","seo":{"title":"External Identifiers Guide"}},"lastModified":"2026-07-02T22:02:49.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/orders/external-identifiers","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}