This guide documents how to create a shipment with sales order items using the ShipEngine API.
POST /v-beta/shipments
POST /v-beta/shipments HTTP/1.1
Host: api.shipengine.com
API-Key: __YOUR_API_KEY_HERE__
Content-Type: application/json{
"shipments": [{
"validate_address": "validate_and_clean",
"carrier_id": "se-123890",
"service_code": "usps_priority_mail",
"ship_to": {
"name": "Amanda Miller",
"phone": "555-555-5555",
"address_line1": "525 S Winchester Blvd",
"city_locality": "San Jose",
"state_province": "CA",
"postal_code": "95128",
"country_code": "US",
"address_residential_indicator": "yes"
},
"warehouse_id": "se-241419",
"packages": [{
"package_code": "package",
"weight": {
"value": 1.0,
"unit": "ounce"
}
}],
"items": [
{
"sales_order_id": "0351523b-1955-5259-a5a5-e63b7336e738",
"sales_order_item_id": "eeda0203-1380-5cf3-a6fd-8b405d0e5bfb",
"quantity": 1
}
]
}]
}Important
When including sales_order_id and sales_order_item_id, ShipEngine will not automatically populate the SKU and name. Users must manually add SKU and name values if needed, which will then be persisted.
The API returns:
- Shipment ID and status
- Address validation results (original vs matched)
- Complete shipment details including ship-to, ship-from, and return-to addresses
- Package information
- Items array with timestamps and optional SKU/name fields
Response includes "has_errors": false for successful creation and "shipment_status": "pending" for new shipments.