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

​Shipment Management

Endpoint

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

​Create a new shipment

POST
https://api.sh.example.com/v1
/shipments

Creates a new shipment with the provided details

​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
  • 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

​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
    • 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

​Track a shipment

GET
https://api.sh.example.com/v1
/shipments/{trackingNumber}

Get the current status and tracking information for a shipment

​Track a shipment › path Parameters

  • trackingNumberstring · required

​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

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

​Cancel shipment

DELETE
https://api.sh.example.com/v1
/shipments/{trackingNumber}

Cancel a shipment that hasn't been picked up yet

​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

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

    • 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 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://api.sh.example.com/v1
/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

    • serviceLevelsobject[]
Rates & Billing