Overview
Shipment API
This API allows you to create and track shipments through the Cosmo Cargo platform.
Authentication
All endpoints require a valid API key passed in the X-API-Key header.
Endpoint
Create a new shipment
POST
https://api.sh.example.com/v1
/shipments
Creates a new shipment with the provided details
Headers
X-Correlation-IDstringUnique identifier for tracking requests across multiple services
Idempotency-KeystringUnique key to ensure idempotency of the request
X-API-VersionstringAPI version requested by the client
X-Request-PrioritystringPriority level for processing the shipment request
Request Body
recipientAddressobjectsenderAddressobjectpackagesobject[]
idstringoptionalstatusstringoptionaltrackingNumberstringoptionalcreatedAtstringoptionalcommentsobject[]optional
Responses
recipientAddressobjectsenderAddressobjectpackagesobject[]idstringoptionalstatusstringoptionaltrackingNumberstringoptionalcreatedAtstringoptionalcommentsobject[]optional
Track a shipment
GET
https://api.sh.example.com/v1
/shipments/{trackingNumber}
Get the current status and tracking information for a shipment
path Parameters
trackingNumberstringrequired
Headers
X-Correlation-IDstringUnique identifier for tracking requests across multiple services
X-API-VersionstringAPI version requested by the client
X-Cache-ControlstringCaching behavior for the tracking response
Responses
recipientAddressobjectsenderAddressobjectpackagesobject[]idstringoptionalstatusstringoptionaltrackingNumberstringoptionalcreatedAtstringoptionalcommentsobject[]optional
Hold shipment
PUT
https://api.sh.example.com/v1
/shipments/{shipmentId}/hold
Place a shipment on hold at a facility
path Parameters
shipmentIdstringrequired
Request Body
holdUntilstring
reasonstringoptionalfacilityIdstringoptional
Responses
statusstringoptionalholdLocationstringoptionalholdUntilstringoptional