In ShipStation API v2, what you might think of as an "order" is actually called a 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.
A shipment in v2 represents the intent to ship something. It contains:
- Ship-to and ship-from addresses
- Package dimensions and weight
- Items being shipped
- Carrier and service preferences
- Custom metadata and identifiers
In the ShipStation UI and v1 API, this same concept was called an order.
A label in v2 represents a purchased shipping label from a carrier. It includes:
- The actual label file (PDF, PNG, ZPL)
- Tracking number
- Shipping cost
- Carrier details
- Associated shipment information
In the ShipStation UI and v1 API, this was called a shipment.
| ShipStation UI / v1 Term | v2 API Term | What It Represents |
|---|---|---|
| Order | Shipment | Intent to ship; order details and addresses |
| order_id | shipment_id | Unique identifier for the shipment (with se- prefix) |
| orderNumber | shipment_number | User-friendly reference number |
| orderKey | external_shipment_id | Your system's identifier for the shipment |
| Shipment | Label | Purchased shipping label from carrier |
| shipment_id | label_id | Unique identifier for the label (with se- prefix) |
The v2 terminology aligns with how most shipping carriers and APIs describe these concepts:
- Shipment = The shipping request/intent (what you're sending and where)
- Label = The physical/digital artifact used to ship it
This makes integration more intuitive for developers familiar with carrier APIs like UPS, FedEx, and USPS, and matches the terminology used by ShipEngine API.
For detailed information about specific aspects of orders and shipments in v2:
- External Identifiers Guide - Learn about
external_shipment_id,external_order_id, and how they relate to v1orderKey - Shipment Numbers & Uniqueness - Understand
shipment_numberuniqueness rules and auto-population - Legacy API Migration - Migration guidance for v1 users and legacy ShipStation UI behavior
- Products and Plans - Terminology Reference - Complete v1 to v2 terminology mapping