External Identifiers Guide

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.

The external_shipment_id is your system's unique identifier for a shipment. This field serves the same purpose as orderKey in the v1 API.

• User-defined: You set this value when creating a shipment
• Optional but recommended: Not required, but strongly recommended for tracking
• Must be unique: Each external_shipment_id must be unique per account
• Immutable: Cannot be changed after shipment creation
• Exists at two levels: Both shipments and labels have this field

Example:

{
  "external_shipment_id": "ORDER-2024-12345",
  "ship_to": { ... },
  "ship_from": { ... }
}

If you do not provide an external_shipment_id when creating a shipment, the API will automatically generate one based on the shipment_id:

• Provided: "external_shipment_id": "MY-ORDER-123" → Uses your value
• Not provided: System generates → "external_shipment_id": "se-123456789"

The external_order_id is a read/write field that represents the ID of an order record in the ShipStation UI system (if one exists).

• System-populated by default: When a shipment is created through certain flows, ShipStation may automatically populate this
• Now user-settable: As of recent updates, you can set this value when creating shipments
• Optional: Not required for API-only workflows
• Different from external_shipment_id: These are two separate concepts

The external_order_id can be populated in several ways:

1. Automatically - When a shipment is imported from a connected sales channel (e.g., Shopify, Amazon)
2. By the system - When using legacy ShipStation UI v2 features
3. By you - You can now explicitly set this value when creating shipments via API

Most API-only integrations do not need to use external_order_id. Use it when:

• You're integrating with the ShipStation UI and need to link API-created shipments to UI orders
• You're migrating from legacy systems that used this field
• You need to track which ShipStation UI order a shipment originated from

Example:

{
  "external_shipment_id": "MY-ORDER-123",
  "external_order_id": "SS-ORDER-456",
  "ship_to": { ... }
}

Both shipments and labels have an external_shipment_id field, and they're closely related:

1. When you create a shipment, you provide external_shipment_id
2. When you create a label from that shipment, the label inherits the shipment's external_shipment_id
3. Both records share the same value, making it easy to link labels back to your original order

Example Flow:

1. Create Shipment
   POST /v2/shipments
   {
     "external_shipment_id": "ORDER-2024-12345",
     ...
   }
   Response: { "shipment_id": "se-123456" }

2. Create Label from Shipment
   POST /v2/labels/shipment/se-123456
   
   Label Response includes:
   {
     "label_id": "se-789012",
     "shipment_id": "se-123456",
     "external_shipment_id": "ORDER-2024-12345"  ← Inherited from shipment
   }

You can retrieve records using external_shipment_id:

GET /v2/labels/external_shipment_id/ORDER-2024-12345
GET /v2/shipments/external_shipment_id/ORDER-2024-12345

This makes it easy to find ShipStation records using your own system's identifiers.

// ✅ Good - Provide your own external_shipment_id
{
  "external_shipment_id": "SHOPIFY-ORDER-98765",
  "ship_to": { ... }
}

// ❌ Not ideal - Relying on auto-generated IDs
{
  // No external_shipment_id provided
  // System will use "se-123456789"
  "ship_to": { ... }
}

Choose a naming pattern and stick with it:

• ORDER-{id} (e.g., ORDER-12345)
• {source}-{id} (e.g., SHOPIFY-98765)
• {prefix}-{date}-{id} (e.g., WEB-20240615-001)

{
  "external_shipment_id": "MY-ORDER-123",    // Your order ID
  "external_order_id": "SS-UI-ORDER-456",    // ShipStation UI order ID (if applicable)
  "shipment_id": "se-789012"                  // ShipStation's internal ID (read-only)
}

• Understanding Orders & Shipments - Core concepts overview
• Shipment Numbers & Uniqueness - Learn about shipment_number
• Legacy API Migration - Migrating from v1 orderKey