Shipment API

Shipment Management

Endpoint

Download schema

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

Filter shipments

GET

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

/shipments

Search and filter shipments using various criteria

Filter shipments › query Parameters

status

string[] · style: form · explode: true

Filter by shipment status

Enum values:

CREATED

IN_TRANSIT

DELIVERED

EXCEPTION

tags

string[]

Filter by tags

Enum values:

FRAGILE

EXPRESS

INTERNATIONAL

CUSTOMS_REQUIRED

object · style: deepObject · explode: true

Filter by creation date range

object

Filter by address criteria

limit

integer · min: 1 · max: 100

Maximum number of results to return

Default: 20

offset

integer · min: 0

Number of results to skip

Default: 0

Filter shipments › Responses

200

Shipments retrieved successfully

object[]

total

integer

Total number of shipments matching the filter

limit

integer

offset

integer

GET/shipments

const options = {method: 'GET'};

fetch('https://8f9618f3bc0f4eec989627ceaafd5e4d_oas.api.mockbin.io//shipments', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

Example Responses

{
  "shipments": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "recipientEmail": "test@example.com",
      "notes": [
        {
          "id": "id",
          "author": "author",
          "text": "text",
          "timestamp": "2024-08-25T15:00:00Z",
          "replies": [
            null
          ]
        }
      ],
      "recipientAddress": {
        "street": "street",
        "city": "city",
        "state": "state",
        "country": "country",
        "postalCode": "postalCode"
      },
      "senderAddress": {
        "street": "street",
        "city": "city",
        "state": "state",
        "country": "country",
        "postalCode": "postalCode"
      },
      "packages": [
        {
          "weight": 0,
          "dimensions": {
            "length": 0,
            "width": 0,
            "height": 0
          }
        }
      ],
      "status": "CREATED",
      "trackingNumber": "trackingNumber",
      "createdAt": "2024-08-25T15:00:00Z",
      "comments": [
        {
          "id": "id",
          "author": "author",
          "text": "text",
          "timestamp": "2024-08-25T15:00:00Z",
          "replies": [
            null
          ]
        }
      ],
      "tags": [
        "FRAGILE"
      ],
      "facilities": [
        "LAX1"
      ],
      "customData": [
        "string"
      ],
      "metadata": {},
      "customFields": {
        "customerReference": "CUST-123",
        "internalNotes": "Handle with care",
        "specialInstructions": "Leave at front desk"
      },
      "facilityCapabilities": {
        "temperatureControl": {
          "enabled": true,
          "lastChecked": "2024-03-15T10:30:00Z"
        },
        "hazardousMaterials": {
          "enabled": false,
          "lastChecked": "2024-03-14T15:45:00Z"
        }
      },
      "tracking": {
        "currentLocation": "Distribution Center - Los Angeles, CA",
        "estimatedDelivery": "2024-08-25T15:00:00Z",
        "lastUpdate": "2024-08-25T15:00:00Z",
        "carrier": "FEDEX",
        "deliveryConfirmation": {
          "signedBy": "signedBy",
          "signatureImage": "https://www.example.com/path/to/resource"
        }
      },
      "returnTracking": {
        "currentLocation": "Distribution Center - Los Angeles, CA",
        "estimatedDelivery": "2024-08-25T15:00:00Z",
        "lastUpdate": "2024-08-25T15:00:00Z",
        "carrier": "FEDEX",
        "deliveryConfirmation": {
          "signedBy": "signedBy",
          "signatureImage": "https://www.example.com/path/to/resource"
        }
      }
    }
  ],
  "total": 0,
  "limit": 0,
  "offset": 0
}

json

application/json

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-ID

string · uuid

Unique identifier for tracking requests across multiple services

Idempotency-Key

string · uuid

Unique key to ensure idempotency of the request

X-API-Version

string | null · enum

API version requested by the client

Enum values:

2024-01

2023-12

Default: 2024-01

X-Request-Priority

string · enum

Priority level for processing the shipment request

Enum values:

high

normal

low

Default: normal

Create a new shipment › Request Body

object · required

object[] · minItems: 1 · maxItems: 50 · unique · required

id

string · uuid

recipientEmail

string · email

object[]

Notes about the shipment

status

string | null · enum

Enum values:

CREATED

IN_TRANSIT

DELIVERED

EXCEPTION

trackingNumber

string · pattern: ^[A-Z0-9]{10,20}$

createdAt

string · date-time

object[] · enum · maxItems: 100

Enum values:

PENDING

APPROVED

REJECTED

tags

string[]

Enum values:

FRAGILE

EXPRESS

INTERNATIONAL

CUSTOMS_REQUIRED

facilities

string[]

Enum values:

LAX1

JFK2

ORD3

DFW4

SEA5

array

Array of custom data items that can be of any type

metadata

object

Empty object for future extensibility

object

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

object

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

object

Detailed tracking information for a shipment

Tracking details for return shipment if applicable

Create a new shipment › Responses

Shipment created successfully

object · required

object[] · minItems: 1 · maxItems: 50 · unique · required

id

string · uuid

recipientEmail

string · email

object[]

Notes about the shipment

status

string | null · enum

Enum values:

CREATED

IN_TRANSIT

DELIVERED

EXCEPTION

trackingNumber

string · pattern: ^[A-Z0-9]{10,20}$

createdAt

string · date-time

object[] · enum · maxItems: 100

Enum values:

PENDING

APPROVED

REJECTED

tags

string[]

Enum values:

FRAGILE

EXPRESS

INTERNATIONAL

CUSTOMS_REQUIRED

facilities

string[]

Enum values:

LAX1

JFK2

ORD3

DFW4

SEA5

array

Array of custom data items that can be of any type

metadata

object

Empty object for future extensibility

object

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

object

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

object

Detailed tracking information for a shipment

Tracking details for return shipment if applicable

POST/shipments

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    recipientEmail: 'test@example.com',
    recipientAddress: {
      street: '123 Delivery St',
      city: 'Shiptown',
      state: 'ST',
      country: 'US',
      postalCode: '12345'
    },
    senderAddress: {
      street: '456 Sender Ave',
      city: 'Packageville',
      state: 'ST',
      country: 'US',
      postalCode: '67890'
    },
    packages: [{weight: 2.5, dimensions: {length: 30, width: 20, height: 15}}]
  })
};

fetch('https://8f9618f3bc0f4eec989627ceaafd5e4d_oas.api.mockbin.io//shipments', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

Example Request Body

{
  "recipientEmail": "test@example.com",
  "recipientAddress": {
    "street": "123 Delivery St",
    "city": "Shiptown",
    "state": "ST",
    "country": "US",
    "postalCode": "12345"
  },
  "senderAddress": {
    "street": "456 Sender Ave",
    "city": "Packageville",
    "state": "ST",
    "country": "US",
    "postalCode": "67890"
  },
  "packages": [
    {
      "weight": 2.5,
      "dimensions": {
        "length": 30,
        "width": 20,
        "height": 15
      }
    }
  ]
}

json

application/json

Example Responses

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "recipientEmail": "test@example.com",
  "recipientAddress": {
    "street": "123 Delivery St",
    "city": "Shiptown",
    "state": "ST",
    "country": "US",
    "postalCode": "12345"
  },
  "senderAddress": {
    "street": "456 Sender Ave",
    "city": "Packageville",
    "state": "ST",
    "country": "US",
    "postalCode": "67890"
  },
  "packages": [
    {
      "weight": 2.5,
      "dimensions": {
        "length": 30,
        "width": 20,
        "height": 15
      }
    }
  ],
  "status": "CREATED",
  "trackingNumber": "SH123456789",
  "createdAt": "2025-01-09T12:00:00Z"
}

json

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

trackingNumber

string · required

Default: SH123456789

Track a shipment › query Parameters

includeHistory

boolean

Include detailed tracking history and events in the response

Default: false

Track a shipment › Headers

X-Correlation-ID

string · uuid

Unique identifier for tracking requests across multiple services

X-API-Version

string | null · enum

API version requested by the client

Enum values:

2024-01

2023-12

Default: 2024-01

X-Cache-Control

string · 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

object · required

object[] · minItems: 1 · maxItems: 50 · unique · required

id

string · uuid

recipientEmail

string · email

object[]

Notes about the shipment

status

string | null · enum

Enum values:

CREATED

IN_TRANSIT

DELIVERED

EXCEPTION

trackingNumber

string · pattern: ^[A-Z0-9]{10,20}$

createdAt

string · date-time

object[] · enum · maxItems: 100

Enum values:

PENDING

APPROVED

REJECTED

tags

string[]

Enum values:

FRAGILE

EXPRESS

INTERNATIONAL

CUSTOMS_REQUIRED

facilities

string[]

Enum values:

LAX1

JFK2

ORD3

DFW4

SEA5

array

Array of custom data items that can be of any type

metadata

object

Empty object for future extensibility

object

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

object

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

object

Detailed tracking information for a shipment

Tracking details for return shipment if applicable

GET/shipments/{trackingNumber}

const options = {method: 'GET'};

fetch('https://8f9618f3bc0f4eec989627ceaafd5e4d_oas.api.mockbin.io//shipments/:trackingNumber', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

Example Responses

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "recipientEmail": "test@example.com",
  "recipientAddress": {
    "street": "123 Delivery St",
    "city": "Shiptown",
    "state": "ST",
    "country": "US",
    "postalCode": "12345"
  },
  "senderAddress": {
    "street": "456 Sender Ave",
    "city": "Packageville",
    "state": "ST",
    "country": "US",
    "postalCode": "67890"
  },
  "packages": [
    {
      "weight": 2.5,
      "dimensions": {
        "length": 30,
        "width": 20,
        "height": 15
      }
    }
  ],
  "status": "IN_TRANSIT",
  "trackingNumber": "SH123456789",
  "createdAt": "2025-01-09T12:00:00Z"
}

json

application/json

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

trackingNumber

string · required

Cancel shipment › Responses

200

Shipment cancelled successfully

status

string · enum

Enum values:

CANCELLED

refundAmount

number · float

currency

string

DELETE/shipments/{trackingNumber}

const options = {method: 'DELETE'};

fetch('https://8f9618f3bc0f4eec989627ceaafd5e4d_oas.api.mockbin.io//shipments/:trackingNumber', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

Example Responses

{
  "status": "CANCELLED",
  "refundAmount": 116.74,
  "currency": "USD"
}

json

application/json

Hold shipment

PUT

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

/shipments/{shipmentId}/hold

Place a shipment on hold at a facility

Hold shipment › path Parameters

shipmentId

string · uuid · required

Hold shipment › query Parameters

holdDuration

string · date-time

Duration to hold the shipment

Hold shipment › Headers

X-Hold-Operator

string · enum

Operator requesting the hold

Enum values:

SYSTEM

ADMIN

CUSTOMER

AGENT

preferredLocation

string

User's preferred facility location

Hold shipment › Request Body

holdUntil

string · date-time · required

reason

string · enum

Enum values:

RECIPIENT_REQUEST

CUSTOMS_HOLD

WEATHER_DELAY

ADDRESS_VERIFICATION

PAYMENT_PENDING

facilityId

string · enum

Enum values:

LAX1

JFK2

ORD3

DFW4

SEA5

Hold shipment › Responses

200

Shipment placed on hold successfully

status

string · enum

Enum values:

ON_HOLD

HOLD_PENDING

HOLD_REJECTED

holdLocation

string · enum

Enum values:

LAX1 - Los Angeles Hub

JFK2 - New York Hub

ORD3 - Chicago Hub

DFW4 - Dallas Hub

SEA5 - Seattle Hub

holdUntil

string · enum · date-time

Enum values:

2025-01-15T17:00:00Z

2025-01-16T09:00:00Z

2025-01-17T14:00:00Z

PUT/shipments/{shipmentId}/hold

const options = {
  method: 'PUT',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    holdUntil: '2025-01-15T17:00:00Z',
    reason: 'RECIPIENT_REQUEST',
    facilityId: 'LAX1'
  })
};

fetch('https://8f9618f3bc0f4eec989627ceaafd5e4d_oas.api.mockbin.io//shipments/:shipmentId/hold', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

Example Request Body

{
  "holdUntil": "2025-01-15T17:00:00Z",
  "reason": "RECIPIENT_REQUEST",
  "facilityId": "LAX1"
}

json

application/json

Example Responses

{
  "status": "ON_HOLD",
  "holdLocation": "LAX1 - Los Angeles Hub",
  "holdUntil": "2025-01-15T17:00:00Z"
}

json

application/json

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

shipmentId

string · uuid · required

Update shipment priority › Request Body

priority

string · enum · required

New priority level for the shipment

Enum values:

URGENT

HIGH

NORMAL

LOW

PUT/shipments/{shipmentId}/priority

const options = {
  method: 'PUT',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({priority: 'URGENT'})
};

fetch('https://8f9618f3bc0f4eec989627ceaafd5e4d_oas.api.mockbin.io//shipments/:shipmentId/priority', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

Example Request Body

{
  "priority": "URGENT"
}

json

Example Responses

No example specified for this content type

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

shipmentId

string · uuid · required

Get available service levels › Responses

200

Available service levels

object[]

GET/shipments/{shipmentId}/service-levels

const options = {method: 'GET'};

fetch('https://8f9618f3bc0f4eec989627ceaafd5e4d_oas.api.mockbin.io//shipments/:shipmentId/service-levels', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

Example Responses

{
  "serviceLevels": [
    {
      "code": "SAME_DAY",
      "name": "name",
      "description": "description"
    }
  ]
}

json

application/json

Create a lost shipment claim

POST

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

/shipments/{shipmentId}/claims

Submit a claim for a lost or damaged shipment. This endpoint accepts multipart/form-data to allow uploading photos and other evidence files along with the claim details.

Supported File Types

Images: JPEG, PNG, GIF, WebP (max 10MB each)
Documents: PDF (max 25MB each)

Maximum Files

You can upload up to 10 files per claim.

Create a lost shipment claim › path Parameters

shipmentId

string · uuid · required

The unique identifier of the shipment

Create a lost shipment claim › Headers

X-Correlation-ID

string · uuid

Unique identifier for tracking requests across multiple services

Idempotency-Key

string · uuid

Unique key to ensure idempotency of the request

Create a lost shipment claim › Request Body

claimType

string · enum · required

The type of claim being filed

Enum values:

LOST

DAMAGED

DELAYED

MISSING_CONTENTS

description

string · minLength: 20 · maxLength: 5000 · required

Detailed description of the issue and circumstances

claimantEmail

string · email · required

Email address for claim correspondence

claimantPhone

string · pattern: ^\+[1-9]\d{1,14}$

Phone number for claim correspondence (E.164 format)

declaredValue

number · float · min: 0

Declared value of the shipment contents in USD

incidentDate

string · date

Date when the incident was discovered

photos

string[] · application/octet-stream · maxItems: 10

Photos of damaged package or contents (JPEG, PNG, GIF, WebP)

documents

string[] · application/octet-stream · maxItems: 5

Supporting documents such as receipts, invoices, or police reports (PDF only)

Create a lost shipment claim › Responses

Claim created successfully

claimId

string · uuid

Unique identifier for the claim

shipmentId

string · uuid

The shipment this claim is associated with

claimNumber

string · pattern: ^CLM-[A-Z0-9]{8}$

Human-readable claim reference number

claimType

string · enum

Enum values:

LOST

DAMAGED

DELAYED

MISSING_CONTENTS

status

string · enum

Current status of the claim

Enum values:

SUBMITTED

UNDER_REVIEW

ADDITIONAL_INFO_REQUIRED

APPROVED

DENIED

SETTLED

declaredValue

number · float

object[]

createdAt

string · date-time

estimatedResolutionDate

string · date

Expected date for claim resolution

POST/shipments/{shipmentId}/claims

const form = new FormData();
form.append('claimType', 'LOST');
form.append('description', 'description');
form.append('claimantEmail', 'test@example.com');
form.append('claimantPhone', 'claimantPhone');
form.append('declaredValue', '0');
form.append('incidentDate', '2024-08-25');
form.append('photos', 'string');
form.append('documents', 'string');

const options = {method: 'POST'};

options.body = form;

fetch('https://8f9618f3bc0f4eec989627ceaafd5e4d_oas.api.mockbin.io//shipments/:shipmentId/claims', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

Example Request Body

{
  "claimType": "LOST",
  "description": "description",
  "claimantEmail": "test@example.com",
  "claimantPhone": "claimantPhone",
  "declaredValue": 0,
  "incidentDate": "2024-08-25",
  "photos": [
    "string"
  ],
  "documents": [
    "string"
  ]
}

json

Example Responses

{
  "claimId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "shipmentId": "123e4567-e89b-12d3-a456-426614174000",
  "claimNumber": "CLM-XK7M9P2Q",
  "claimType": "DAMAGED",
  "status": "SUBMITTED",
  "declaredValue": 299.99,
  "uploadedFiles": [
    {
      "fileId": "f1e2d3c4-b5a6-7890-1234-567890abcdef",
      "fileName": "damaged_box.jpg",
      "fileType": "PHOTO",
      "uploadedAt": "2025-01-15T10:30:00Z"
    },
    {
      "fileId": "a9b8c7d6-e5f4-3210-9876-543210fedcba",
      "fileName": "purchase_receipt.pdf",
      "fileType": "DOCUMENT",
      "uploadedAt": "2025-01-15T10:30:00Z"
    }
  ],
  "createdAt": "2025-01-15T10:30:00Z",
  "estimatedResolutionDate": "2025-01-29"
}

json

application/json

Notifications

Shipment Management

Filter shipments

Filter shipments › query Parameters

Filter shipments › Responses

Create a new shipment

How to use with SDK

Create a new shipment › Headers

Create a new shipment › Request Body

Create a new shipment › Responses

Track a shipment

Track a shipment › path Parameters

Track a shipment › query Parameters

Track a shipment › Headers

Track a shipment › Responses

Cancel shipment

Cancel shipment › path Parameters

Cancel shipment › Responses

Hold shipment

Hold shipment › path Parameters

Hold shipment › query Parameters

Hold shipment › Headers

Hold shipment › cookie Parameters

Hold shipment › Request Body

Hold shipment › Responses

Update shipment priority

Update shipment priority › path Parameters

Update shipment priority › Request Body

Get available service levels

Get available service levels › path Parameters

Get available service levels › Responses

Create a lost shipment claim

Supported File Types

Maximum Files

Create a lost shipment claim › path Parameters

Create a lost shipment claim › Headers

Create a lost shipment claim › Request Body

Create a lost shipment claim › Responses

Shipment Management

Filter shipments

Filter shipments › query Parameters

Filter shipments › Responses

Create a new shipment

How to use with SDK

Create a new shipment › Headers

Create a new shipment › Request Body

Create a new shipment › Responses

Track a shipment

Track a shipment › path Parameters

Track a shipment › query Parameters

Track a shipment › Headers

Track a shipment › Responses

Cancel shipment

Cancel shipment › path Parameters

Cancel shipment › Responses

Hold shipment

Hold shipment › path Parameters

Hold shipment › query Parameters

Hold shipment › Headers

Hold shipment › cookie Parameters

Hold shipment › Request Body

Hold shipment › Responses

Update shipment priority

Update shipment priority › path Parameters

Update shipment priority › Request Body

Get available service levels

Get available service levels › path Parameters

Get available service levels › Responses

Create a lost shipment claim

Supported File Types

Maximum Files

Create a lost shipment claim › path Parameters

Create a lost shipment claim › Headers

Create a lost shipment claim › Request Body

Create a lost shipment claim › Responses