{"templateId":"markdown","versions":[{"version":"shipengine","label":"ShipStation API (formerly ShipEngine)","link":"/apis/shipengine/docs/orders/legacy-migration","default":false,"active":false,"folderId":"58c9a61d"},{"version":"shipstation-v2","label":"ShipStation V2 API","link":"/apis/docs/orders/legacy-migration","default":true,"active":true,"folderId":"58c9a61d"},{"version":"shipstation-v1","label":"ShipStation V1 API","link":"/apis/shipstation-v1/docs/orders/legacy-migration","default":false,"active":false,"folderId":"58c9a61d"}],"sharedDataIds":{"sidebar":"sidebar-apis/@shipengine/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"type":"markdown"},"seo":{"title":"Legacy API Migration","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":"legacy-api-migration","__idx":0},"children":["Legacy API Migration"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Migrating from ShipStation Companion API (v1) to v2 requires understanding key differences in how orders, shipments, and identifiers work. This guide focuses on the practical migration steps and gotchas."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"key-id-translations","__idx":1},"children":["Key ID Translations"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"orderkey--external_shipment_id","__idx":2},"children":["orderKey → external_shipment_id"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The v1 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["orderKey"]}," field maps directly to v2's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["external_shipment_id"]},":"]},{"$$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 Field"]}]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":""},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["v2 Field"]}]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":""},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Migration Notes"]}]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["orderKey"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["external_shipment_id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Same concept, just renamed"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["v1 Example:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"orderKey\": \"MY-ORDER-123\",\n  \"orderNumber\": \"ORD-123\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["v2 Equivalent:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"external_shipment_id\": \"MY-ORDER-123\",\n  \"shipment_number\": \"ORD-123\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"internal-id-prefixes","__idx":3},"children":["Internal ID Prefixes"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["All v2 internal IDs use the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["se-"]}," prefix:"]},{"$$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 Field"]}]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":""},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["v1 Value"]}]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":""},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["v2 Field"]}]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":""},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["v2 Value"]}]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["orderId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["12345678"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["shipment_id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["se-12345678"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["shipmentId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["87654321"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["label_id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["se-87654321"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"Always Prepend se-"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When migrating ID references from v1 to v2, you must prepend ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["se-"]}," to the numeric ID:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["v1 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["orderId"]},": ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["12345678"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["v2 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["shipment_id"]},": ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["se-12345678"]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["JavaScript Example:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","header":{"controls":{"copy":{}}},"source":"// Converting v1 orderId to v2 shipment_id\nconst v1OrderId = 12345678;\nconst v2ShipmentId = `se-${v1OrderId}`;  // \"se-12345678\"\n","lang":"javascript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"status-value-mapping","__idx":4},"children":["Status Value Mapping"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["v2 uses different status values than v1:"]},{"$$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 orderStatus"]}]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":""},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["v2 shipment_status"]}]},{"$$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":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["awaiting_payment"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pending"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["⚠️ Many-to-one mapping"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["awaiting_shipment"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pending"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["⚠️ Many-to-one mapping"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["on_hold"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pending"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["⚠️ Many-to-one mapping"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["(no v1 equivalent)"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["processing"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["v2/ShipEngine only - transient status during async label creation"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["shipped"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["label_purchased"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Different terminology"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cancelled"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cancelled"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Same value"]}]}]}]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"Loss of Status Granularity"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Critical Issue:"]}," Three distinct v1 statuses (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["awaiting_payment"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["awaiting_shipment"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["on_hold"]},") all map to a single v2 status (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pending"]},")."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This means you ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["cannot determine the specific v1 status"]}," from a v2 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pending"]}," status without storing additional metadata in your system."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Workaround:"]}," If you need to preserve v1 status granularity, store the original v1 status in custom metadata fields or your own database."]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"About the processing Status"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["processing"]}," status is a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["transient state"]}," that only exists in v2/ShipEngine during async label creation. When you trigger label creation for a shipment, it briefly enters ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["processing"]}," status before transitioning to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["label_purchased"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you query a shipment and see ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["processing"]},", wait a few seconds and query again - it should have transitioned to its final state."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This status did not exist in v1."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"legacy-shipstation-ui-v2-behavior","__idx":5},"children":["Legacy ShipStation UI v2 Behavior"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you're using the legacy ShipStation UI alongside the v2 API, there's an important behavior to understand."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"shipments-appear-as-orders-in-ui","__idx":6},"children":["Shipments Appear as Orders in UI"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When you create a shipment via the v2 API, ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["it will appear as an \"order\" in the ShipStation UI"]},", even if you do NOT pass ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["create_sales_order: true"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Why This Happens:"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The legacy ShipStation UI v2 system still uses the \"order\" terminology and treats API-created shipments as orders for display purposes. This is a backwards-compatibility feature."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["What You'll See:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"API: POST /v2/shipments\n{\n  \"external_shipment_id\": \"ORDER-123\",\n  // create_sales_order not specified or false\n  ...\n}\n\nShipStation UI: Shows this as an \"Order\" with number \"ORDER-123\"\n"},"children":[]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"This is Expected Behavior"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This is ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["not a bug"]},". The ShipStation UI v2 displays API-created shipments as orders to maintain consistency with how users expect the UI to work. The underlying data model is still a v2 shipment."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"the-create_sales_order-flag","__idx":7},"children":["The create_sales_order Flag"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["create_sales_order"]}," flag has a specific purpose:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"external_shipment_id\": \"ORDER-123\",\n  \"create_sales_order\": true,  // Creates a sales order record\n  ...\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["When ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["create_sales_order"]}," is true:"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Creates both a shipment AND a separate sales order record in the UI system"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Populates ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["external_order_id"]}," field automatically"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Links the shipment to the sales order"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["When ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["create_sales_order"]}," is false or omitted:"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Creates only a shipment (which still appears as an \"order\" in UI)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["No separate sales order record is created"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["external_order_id"]}," may be null or auto-populated depending on context"]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"success","name":"When to Use create_sales_order"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["create_sales_order: true"]}," when:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["You want to create a full sales order record in the ShipStation UI system"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["You're integrating with sales channel imports"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["You need the sales order/shipment separation in the UI"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For most API-only integrations, you can omit this flag."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"migration-checklist","__idx":8},"children":["Migration Checklist"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"1-update-field-names","__idx":9},"children":["1. Update Field Names"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","header":{"controls":{"copy":{}}},"source":"// ❌ v1 field names\n{\n  orderKey: \"ORDER-123\",\n  orderNumber: \"ORD-123\",\n  orderDate: \"2024-06-15T10:00:00Z\"\n}\n\n// ✅ v2 field names\n{\n  external_shipment_id: \"ORDER-123\",\n  shipment_number: \"ORD-123\",\n  created_at: \"2024-06-15T10:00:00Z\"\n}\n","lang":"javascript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"2-add-se--prefix-to-ids","__idx":10},"children":["2. Add se- Prefix to IDs"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","header":{"controls":{"copy":{}}},"source":"// v1 to v2 ID conversion helper\nfunction convertV1IdsToV2(v1Record) {\n  return {\n    shipment_id: `se-${v1Record.orderId}`,\n    label_id: v1Record.shipmentId ? `se-${v1Record.shipmentId}` : null\n  };\n}\n","lang":"javascript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"3-handle-status-mapping","__idx":11},"children":["3. Handle Status Mapping"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","header":{"controls":{"copy":{}}},"source":"// v1 to v2 status conversion\nconst statusMap = {\n  'awaiting_payment': 'pending',\n  'awaiting_shipment': 'pending',\n  'on_hold': 'pending',\n  'shipped': 'label_purchased',\n  'cancelled': 'cancelled'\n};\n\nfunction convertStatus(v1Status) {\n  return statusMap[v1Status] || 'pending';\n}\n","lang":"javascript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"4-store-original-v1-statuses-if-needed","__idx":12},"children":["4. Store Original v1 Statuses (if needed)"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"external_shipment_id\": \"ORDER-123\",\n  \"shipment_status\": \"pending\",\n  \"metadata\": {\n    \"legacy_v1_status\": \"awaiting_payment\"  // Preserve original status\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"5-update-api-endpoints","__idx":13},"children":["5. Update API Endpoints"]},{"$$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 Endpoint"]}]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":""},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["v2 Endpoint"]}]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /orders/{orderId}"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v2/shipments/{shipment_id}"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /orders?orderNumber={num}"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v2/shipments?shipment_number={num}"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /shipments/{shipmentId}"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v2/labels/{label_id}"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /orders/createorder"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v2/shipments"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /orders/createlabelfororder"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v2/labels/shipment/{shipment_id}"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"common-migration-pitfalls","__idx":14},"children":["Common Migration Pitfalls"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"pitfall-1-forgetting-se--prefix","__idx":15},"children":["Pitfall 1: Forgetting se- Prefix"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","header":{"controls":{"copy":{}}},"source":"// ❌ Wrong - Using numeric ID directly\nconst response = await fetch(`/v2/shipments/${12345678}`);\n\n// ✅ Correct - Adding se- prefix\nconst response = await fetch(`/v2/shipments/se-${12345678}`);\n","lang":"javascript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"pitfall-2-assuming-status-equivalence","__idx":16},"children":["Pitfall 2: Assuming Status Equivalence"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","header":{"controls":{"copy":{}}},"source":"// ❌ Wrong - Assuming you can reverse-map from v2 to v1\nconst v2Status = 'pending';\n// Can't tell if this was awaiting_payment, awaiting_shipment, or on_hold!\n\n// ✅ Correct - Store original status if you need it\nconst metadata = shipment.metadata?.legacy_v1_status;\n","lang":"javascript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"pitfall-3-not-understanding-ui-behavior","__idx":17},"children":["Pitfall 3: Not Understanding UI Behavior"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","header":{"controls":{"copy":{}}},"source":"// This WILL show up in ShipStation UI as an \"order\"\n// even though create_sales_order is false\nawait createShipment({\n  external_shipment_id: \"ORDER-123\",\n  create_sales_order: false  // Still appears in UI!\n});\n","lang":"javascript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"related-guides","__idx":18},"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/external-identifiers"},"children":["External Identifiers Guide"]}]}," - Deep dive on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["external_shipment_id"]}," vs 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"]}]}," - Understanding ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["shipment_number"]}," vs v1 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["orderNumber"]}]},{"$$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 v2 concepts"]},{"$$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 field mapping table"]}]}]},"headings":[{"value":"Legacy API Migration","id":"legacy-api-migration","depth":1},{"value":"Key ID Translations","id":"key-id-translations","depth":2},{"value":"orderKey → external_shipment_id","id":"orderkey--external_shipment_id","depth":3},{"value":"Internal ID Prefixes","id":"internal-id-prefixes","depth":3},{"value":"Status Value Mapping","id":"status-value-mapping","depth":2},{"value":"Legacy ShipStation UI v2 Behavior","id":"legacy-shipstation-ui-v2-behavior","depth":2},{"value":"Shipments Appear as Orders in UI","id":"shipments-appear-as-orders-in-ui","depth":3},{"value":"The create_sales_order Flag","id":"the-create_sales_order-flag","depth":3},{"value":"Migration Checklist","id":"migration-checklist","depth":2},{"value":"1. Update Field Names","id":"1-update-field-names","depth":3},{"value":"2. Add se- Prefix to IDs","id":"2-add-se--prefix-to-ids","depth":3},{"value":"3. Handle Status Mapping","id":"3-handle-status-mapping","depth":3},{"value":"4. Store Original v1 Statuses (if needed)","id":"4-store-original-v1-statuses-if-needed","depth":3},{"value":"5. Update API Endpoints","id":"5-update-api-endpoints","depth":3},{"value":"Common Migration Pitfalls","id":"common-migration-pitfalls","depth":2},{"value":"Pitfall 1: Forgetting se- Prefix","id":"pitfall-1-forgetting-se--prefix","depth":3},{"value":"Pitfall 2: Assuming Status Equivalence","id":"pitfall-2-assuming-status-equivalence","depth":3},{"value":"Pitfall 3: Not Understanding UI Behavior","id":"pitfall-3-not-understanding-ui-behavior","depth":3},{"value":"Related Guides","id":"related-guides","depth":2}],"frontmatter":{"slug":"/orders/legacy-migration","seo":{"title":"Legacy API Migration"}},"lastModified":"2026-07-02T22:02:49.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/orders/legacy-migration","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}