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

​Shipment Management

Endpoint

​Create a new shipment

POST
https://api.sh.example.com/v1
/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://api.sh.example.com/v1
/shipments/{trackingNumber}

​Track a shipment › path Parameters

  • trackingNumberstring · required

​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://api.sh.example.com/v1
/shipments/{trackingNumber}

​Cancel shipment › path Parameters

  • trackingNumberstring · required

​Cancel shipment › Responses

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

​Hold shipment

PUT
https://api.sh.example.com/v1
/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://api.sh.example.com/v1
/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://api.sh.example.com/v1
/shipments/{shipmentId}/service-levels

​Get available service levels › path Parameters

  • shipmentIdstring · uuid · required

​Get available service levels › Responses

    • serviceLevelsobject[]
Rates & Billing