Shipment Numbers & Uniqueness

The shipment_number is a user-friendly, human-readable identifier for shipments. Understanding how it works and its relationship to external_shipment_id is important for proper integration.

The shipment_number is equivalent to orderNumber in the v1 API and Order Number in the ShipStation UI. It's designed to be:

• Human-readable: Easy to reference in conversations and support tickets
• Not unique: Multiple shipments can have the same shipment_number (just like Order Numbers in V1/UI)
• Optional: You can provide your own or let the system generate one
• Mutable: Can be updated after creation (unlike external_shipment_id)

The shipment_number field has NO uniqueness enforcement:

• ✅ Multiple shipments can have the same shipment_number
• ✅ This mirrors the behavior of Order Number in V1 API and ShipStation UI
• ✅ You will not receive errors for duplicate shipment_number values

This allows for common scenarios like:

• Multiple partial shipments from the same order sharing the same display number
• Re-creating canceled shipments with the same number
• Using simple sequential numbers without complex collision handling

The external_shipment_id is functionally identical to orderKey in the V1 API:

• Identifies the ORDER, not the individual shipment
• Multiple shipments can (and often do) share the same external_shipment_id
• Common in split-shipping scenarios where one order results in multiple shipments
• Immutable once set (cannot be changed after shipment creation)

ShipStation follows a duplication rule when fields are not provided:

{
  "external_shipment_id": "ORDER-2024-12345",
  "shipment_number": "ORD-12345",
  ...
}

Result: Both values are used as provided.

{
  "external_shipment_id": "ORDER-2024-12345",
  // shipment_number not provided
  ...
}

Result:

• external_shipment_id = "ORDER-2024-12345" (your value)
• shipment_number = "ORDER-2024-12345" (duplicated from external_shipment_id)

{
  // external_shipment_id not provided
  "shipment_number": "ORD-12345",
  ...
}

Result:

• shipment_number = "ORD-12345" (your value)
• external_shipment_id = "se-123456789" (system-generated based on shipment_id)

{
  // Neither field provided
  ...
}

Result: Both are auto-generated based on the internal shipment_id:

• external_shipment_id = "se-123456789"
• shipment_number = "se-123456789"

// ✅ Good - Clear, readable identifiers
{
  "external_shipment_id": "SHOPIFY-ORDER-98765",
  "shipment_number": "WEB-2024-0615-001"
}

// ❌ Not ideal - Cryptic or auto-generated values
{
  "external_shipment_id": "se-123456789",
  "shipment_number": "se-123456789"
}

When creating multiple shipments from the same order, use the same identifiers:

// First shipment
{
  "external_shipment_id": "ORDER-12345",  // Same for all shipments from this order
  "shipment_number": "ORDER-12345",       // Same display number
  "packages": [
    // ... first package
  ]
}

// Second shipment (split from same order)
{
  "external_shipment_id": "ORDER-12345",  // Same - identifies the order
  "shipment_number": "ORDER-12345",       // Same - customer sees one order number
  "packages": [
    // ... remaining packages
  ]
}

If your external_shipment_id values are already user-friendly, just provide that:

{
  "external_shipment_id": "ORDER-2024-06-15-001"
  // shipment_number will automatically duplicate: "ORDER-2024-06-15-001"
}

This reduces redundancy and ensures consistency.

Unlike external_shipment_id, you can update the shipment_number after creation:

PUT /v2/shipments/se-123456
{
  "shipment_number": "NEW-NUMBER-456"
}

Since uniqueness is not enforced, you won't encounter conflicts when updating this field.

{
  "external_shipment_id": "SHOPIFY-98765",  // Tracks the Shopify order
  "shipment_number": "ORDER-2024-001",       // What customers see
}

{
  "external_shipment_id": "UUID-a1b2c3d4",
  "shipment_number": "100001",  // Sequential counter
}

{
  "external_shipment_id": "INTERNAL-789",
  "shipment_number": "20240615-001",  // YYYYMMDD-sequence
}

• External Identifiers Guide - Deep dive on external_shipment_id and external_order_id
• Understanding Orders & Shipments - Core concepts overview
• Legacy API Migration - Migrating from v1 orderKey and orderNumber