We're announcing 🧑‍🚀 inter-galactic shipping ✨ for 3025!
Cosmo Cargo Inc.
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:

tsCode
 
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"}}
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"}}
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"}}
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

Hold shipment › cookie Parameters

  • 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[]
Rates & Billing