Shipment API

Shipment Management

Endpoint

Endpoints for creating, tracking, updating, and managing shipments.

Create a new shipment

POST

https://8f9618f3bc0f4eec989627ceaafd5e4d_oas.api.mockbin.io

/shipments

Creates a new shipment with the provided details.

This endpoint allows you to create and register a new shipment in the Cosmo Cargo platform. The shipment will be assigned a unique trackingNumber and will enter the CREATED status.

How to use with SDK

Here's how to create a shipment using @cosmo-cargo/sdk:


Code
 
import { CosmoCargoClient } from '@cosmo-cargo/sdk';

const client = new CosmoCargoClient({ key: process.env.COSMO_API_KEY });

const shipment = await client.shipments.create(config);
console.log(`Shipment created: ${shipment.trackingNumber}`);

Note: Use the X-Request-Priority header to expedite processing for urgent shipments.

Create a new shipment › Headers

X-Correlation-IDstring · uuid
Unique identifier for tracking requests across multiple services
Idempotency-Keystring · uuid
Unique key to ensure idempotency of the request
X-API-Versionstring | null · enum
API version requested by the client
Enum values:
2024-01
2023-12
Default: 2024-01
X-Request-Prioritystring · enum
Priority level for processing the shipment request
Enum values:
high
normal
low
Default: normal

Create a new shipment › Request Body

recipientAddressobject · required
senderAddressobject · required
packagesobject[] · minItems: 1 · maxItems: 50 · unique · required

idstring · uuid
Example: 123e4567-e89b-12d3-a456-426614174000
recipientEmailstring · email
Example: recipient@example.com
notesobject[]
Notes about the shipment
statusstring | null · enum
Enum values:
CREATED
IN_TRANSIT
DELIVERED
EXCEPTION
trackingNumberstring · pattern: ^[A-Z0-9]{10,20}$
createdAtstring · date-time
commentsobject[] · enum · maxItems: 100
Enum values:
PENDING
APPROVED
REJECTED
tagsstring[]
Enum values:
FRAGILE
EXPRESS
INTERNATIONAL
CUSTOMS_REQUIRED
facilitiesstring[]
Enum values:
LAX1
JFK2
ORD3
DFW4
SEA5
customDataarray
Array of custom data items that can be of any type
metadataobject
Empty object for future extensibility
customFieldsobject
Dictionary of custom string fields that can be added to the shipment
Example: {"customerReference":"CUST-123","internalNotes":"Handle with care","specialInstructions":"Leave at front desk"}
facilityCapabilitiesobject
Dictionary of facility capabilities and their status
Example: {"temperatureControl":{"enabled":true,"lastChecked":"2024-03-15T10:30:00Z"},"hazardousMaterials":{"enabled":false,"lastChecked":"2024-03-14T15:45:00Z"}}
trackingobject
Detailed tracking information for a shipment
returnTracking
Tracking details for return shipment if applicable

Additional properties are allowed

Create a new shipment › Responses

Shipment created successfully

recipientAddressobject · required
senderAddressobject · required
packagesobject[] · minItems: 1 · maxItems: 50 · unique · required

idstring · uuid
Example: 123e4567-e89b-12d3-a456-426614174000
recipientEmailstring · email
Example: recipient@example.com
notesobject[]
Notes about the shipment
statusstring | null · enum
Enum values:
CREATED
IN_TRANSIT
DELIVERED
EXCEPTION
trackingNumberstring · pattern: ^[A-Z0-9]{10,20}$
createdAtstring · date-time
commentsobject[] · enum · maxItems: 100
Enum values:
PENDING
APPROVED
REJECTED
tagsstring[]
Enum values:
FRAGILE
EXPRESS
INTERNATIONAL
CUSTOMS_REQUIRED
facilitiesstring[]
Enum values:
LAX1
JFK2
ORD3
DFW4
SEA5
customDataarray
Array of custom data items that can be of any type
metadataobject
Empty object for future extensibility
customFieldsobject
Dictionary of custom string fields that can be added to the shipment
Example: {"customerReference":"CUST-123","internalNotes":"Handle with care","specialInstructions":"Leave at front desk"}
facilityCapabilitiesobject
Dictionary of facility capabilities and their status
Example: {"temperatureControl":{"enabled":true,"lastChecked":"2024-03-15T10:30:00Z"},"hazardousMaterials":{"enabled":false,"lastChecked":"2024-03-14T15:45:00Z"}}
trackingobject
Detailed tracking information for a shipment
returnTracking
Tracking details for return shipment if applicable

Additional properties are allowed

Track a shipment

GET

https://8f9618f3bc0f4eec989627ceaafd5e4d_oas.api.mockbin.io

/shipments/{trackingNumber}

Get the current status and tracking information for a shipment

Track a shipment › path Parameters

trackingNumberstring · required
Default: SH123456789

Track a shipment › query Parameters

includeHistoryboolean
Include detailed tracking history and events in the response
Default: false

Track a shipment › Headers

X-Correlation-IDstring · uuid
Unique identifier for tracking requests across multiple services
X-API-Versionstring | null · enum
API version requested by the client
Enum values:
2024-01
2023-12
Default: 2024-01
X-Cache-Controlstring · enum
Caching behavior for the tracking response
Enum values:
no-cache
max-age=60
Default: max-age=60

Track a shipment › Responses

Shipment tracking information retrieved successfully

recipientAddressobject · required
senderAddressobject · required
packagesobject[] · minItems: 1 · maxItems: 50 · unique · required

idstring · uuid
Example: 123e4567-e89b-12d3-a456-426614174000
recipientEmailstring · email
Example: recipient@example.com
notesobject[]
Notes about the shipment
statusstring | null · enum
Enum values:
CREATED
IN_TRANSIT
DELIVERED
EXCEPTION
trackingNumberstring · pattern: ^[A-Z0-9]{10,20}$
createdAtstring · date-time
commentsobject[] · enum · maxItems: 100
Enum values:
PENDING
APPROVED
REJECTED
tagsstring[]
Enum values:
FRAGILE
EXPRESS
INTERNATIONAL
CUSTOMS_REQUIRED
facilitiesstring[]
Enum values:
LAX1
JFK2
ORD3
DFW4
SEA5
customDataarray
Array of custom data items that can be of any type
metadataobject
Empty object for future extensibility
customFieldsobject
Dictionary of custom string fields that can be added to the shipment
Example: {"customerReference":"CUST-123","internalNotes":"Handle with care","specialInstructions":"Leave at front desk"}
facilityCapabilitiesobject
Dictionary of facility capabilities and their status
Example: {"temperatureControl":{"enabled":true,"lastChecked":"2024-03-15T10:30:00Z"},"hazardousMaterials":{"enabled":false,"lastChecked":"2024-03-14T15:45:00Z"}}
trackingobject
Detailed tracking information for a shipment
returnTracking
Tracking details for return shipment if applicable

Additional properties are allowed

Cancel shipment

DELETE

https://8f9618f3bc0f4eec989627ceaafd5e4d_oas.api.mockbin.io

/shipments/{trackingNumber}

Cancel a shipment that hasn't been picked up yet

Cancel shipment › path Parameters

trackingNumberstring · required

Cancel shipment › Responses

Shipment cancelled successfully

statusstring · enum
Enum values:
CANCELLED
refundAmountnumber · float
currencystring

Hold shipment

PUT

https://8f9618f3bc0f4eec989627ceaafd5e4d_oas.api.mockbin.io

/shipments/{shipmentId}/hold

Place a shipment on hold at a facility

Hold shipment › path Parameters

shipmentIdstring · uuid · required

Hold shipment › query Parameters

holdDurationstring · date-time
Duration to hold the shipment

Hold shipment › Headers

X-Hold-Operatorstring · enum
Operator requesting the hold
Enum values:
SYSTEM
ADMIN
CUSTOMER
AGENT

preferredLocationstring
User's preferred facility location

Hold shipment › Request Body

holdUntilstring · date-time · required

reasonstring · enum
Enum values:
RECIPIENT_REQUEST
CUSTOMS_HOLD
WEATHER_DELAY
ADDRESS_VERIFICATION
PAYMENT_PENDING
facilityIdstring · enum
Enum values:
LAX1
JFK2
ORD3
DFW4
SEA5

Hold shipment › Responses

Shipment placed on hold successfully

statusstring · enum
Enum values:
ON_HOLD
HOLD_PENDING
HOLD_REJECTED
holdLocationstring · enum
Enum values:
LAX1 - Los Angeles Hub
JFK2 - New York Hub
ORD3 - Chicago Hub
DFW4 - Dallas Hub
SEA5 - Seattle Hub
holdUntilstring · enum · date-time
Enum values:
2025-01-15T17:00:00Z
2025-01-16T09:00:00Z
2025-01-17T14:00:00Z

Update shipment priority

PUT

https://8f9618f3bc0f4eec989627ceaafd5e4d_oas.api.mockbin.io

/shipments/{shipmentId}/priority

Update the priority level of a shipment

Update shipment priority › path Parameters

shipmentIdstring · uuid · required

Update shipment priority › Request Body

prioritystring · enum · required
New priority level for the shipment
Enum values:
URGENT
HIGH
NORMAL
LOW

Get available service levels

GET

https://8f9618f3bc0f4eec989627ceaafd5e4d_oas.api.mockbin.io

/shipments/{shipmentId}/service-levels

Get all available service levels for a shipment with their details

Get available service levels › path Parameters

shipmentIdstring · uuid · required

Get available service levels › Responses

Available service levels

serviceLevelsobject[]

🔔 Notifications

Create a new shipment

POST

https://8f9618f3bc0f4eec989627ceaafd5e4d_oas.api.mockbin.io

/shipments

Creates a new shipment with the provided details.

This endpoint allows you to create and register a new shipment in the Cosmo Cargo platform. The shipment will be assigned a unique trackingNumber and will enter the CREATED status.