We're announcing 🧑‍🚀 inter-galactic shipping ✨ for 3025!
Cosmo Cargo Inc.
Shipment API

Shipment Management

Endpoint

Create a new shipment

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

Create a new shipment › Headers

  • X-Correlation-IDstring · uuid
  • Idempotency-Keystring · uuid
  • X-API-Versionstring | null · enum
    Enum values:
    2024-01
    2023-12
    Default: 2024-01
  • X-Request-Prioritystring · enum
    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[]
  • 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
  • metadataobject
  • customFieldsobject
    Example: {"customerReference":"CUST-123","internalNotes":"Handle with care","specialInstructions":"Leave at front desk"}
  • facilityCapabilitiesobject
    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

  • 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[]
  • 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
  • metadataobject
  • customFieldsobject
    Example: {"customerReference":"CUST-123","internalNotes":"Handle with care","specialInstructions":"Leave at front desk"}
  • facilityCapabilitiesobject
    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}

Track a shipment › path Parameters

  • trackingNumberstring · required
    Default: SH123456789

Track a shipment › query Parameters

  • includeHistoryboolean
    Default: false

Track a shipment › Headers

  • X-Correlation-IDstring · uuid
  • X-API-Versionstring | null · enum
    Enum values:
    2024-01
    2023-12
    Default: 2024-01
  • X-Cache-Controlstring · enum
    Enum values:
    no-cache
    max-age=60
    Default: max-age=60

Track a shipment › Responses

  • 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[]
  • 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
  • metadataobject
  • customFieldsobject
    Example: {"customerReference":"CUST-123","internalNotes":"Handle with care","specialInstructions":"Leave at front desk"}
  • facilityCapabilitiesobject
    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 shipment › path Parameters

  • trackingNumberstring · required

Cancel shipment › Responses

  • statusstring · enum
    Enum values:
    CANCELLED
  • refundAmountnumber · float
  • currencystring

Hold shipment

PUT
https://8f9618f3bc0f4eec989627ceaafd5e4d_oas.api.mockbin.io
/shipments/{shipmentId}/hold

Hold shipment › path Parameters

  • shipmentIdstring · uuid · required

Hold shipment › query Parameters

  • holdDurationstring · date-time

Hold shipment › Headers

  • X-Hold-Operatorstring · enum
    Enum values:
    SYSTEM
    ADMIN
    CUSTOMER
    AGENT

Hold shipment › cookie Parameters

  • preferredLocationstring

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

  • 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 shipment priority › path Parameters

  • shipmentIdstring · uuid · required

Update shipment priority › Request Body

  • prioritystring · enum · required
    Enum values:
    URGENT
    HIGH
    NORMAL
    LOW

Get available service levels

GET
https://8f9618f3bc0f4eec989627ceaafd5e4d_oas.api.mockbin.io
/shipments/{shipmentId}/service-levels

Get available service levels › path Parameters

  • shipmentIdstring · uuid · required

Get available service levels › Responses

  • serviceLevelsobject[]
Rates & Billing