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

​Shipment API

This API allows you to create and track shipments through the Ship Happens platform.

Authentication

All endpoints require a valid API key passed in the X-API-Key header.

Endpoint
Shipment Management

​Create a new shipment

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

Creates a new shipment with the provided details

​Request Body

  • recipientAddress
    object
  • senderAddress
    object
  • packages
    object[]
  • id
    string
    optional
  • status
    string
    optional
  • trackingNumber
    string
    optional
  • createdAt
    string
    optional

​Responses

    • recipientAddress
      object
    • senderAddress
      object
    • packages
      object[]
    • id
      string
      optional
    • status
      string
      optional
    • trackingNumber
      string
      optional
    • createdAt
      string
      optional

​Track a shipment

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

Get the current status and tracking information for a shipment

​path Parameters

  • trackingNumber
    string
    required

​Responses

    • recipientAddress
      object
    • senderAddress
      object
    • packages
      object[]
    • id
      string
      optional
    • status
      string
      optional
    • trackingNumber
      string
      optional
    • createdAt
      string
      optional

​Hold shipment

PUT
https://api.sh.example.com/v1
/shipments/{shipmentId}/hold

Place a shipment on hold at a facility

​path Parameters

  • shipmentId
    string
    required

​Request Body

  • holdUntil
    string
  • reason
    string
    optional
  • facilityId
    string
    optional

​Responses

    • status
      string
      optional
    • holdLocation
      string
      optional
    • holdUntil
      string
      optional
Rates & Billing

​Calculate shipping rates

POST
https://api.sh.example.com/v1
/shipments/{shipmentId}/rates

Calculate available shipping rates for a shipment based on service level, destination, and package details

​path Parameters

  • shipmentId
    string
    required

​Request Body

  • serviceLevel
    string
  • insurance
    object
    optional

​Responses

    • baseRate
      number
      optional
    • fees
      object[]
      optional
    • totalRate
      number
      optional
    • currency
      string
      optional
    • transitTime
      object
      optional

​Add insurance

POST
https://api.sh.example.com/v1
/shipments/{shipmentId}/insurance

Add or modify insurance coverage for a shipment

​path Parameters

  • shipmentId
    string
    required

​Request Body

  • coverage
    number
  • items
    object[]
    optional

​Responses

    • premium
      number
      optional
    • coverage
      number
      optional
    • policyNumber
      string
      optional
International Shipping

​Update customs documentation

PUT
https://api.sh.example.com/v1
/shipments/{shipmentId}/customs

Update or add customs documentation for international shipments

​path Parameters

  • shipmentId
    string
    required

​Request Body

  • items
    object[]
  • purpose
    string
    optional
  • incoterm
    string
    optional

​Responses

    • id
      string
      optional
    • status
      string
      optional
    • customsValue
      number
      optional
    • currency
      string
      optional
    • documents
      object[]
      optional

​Pay import duties

POST
https://api.sh.example.com/v1
/shipments/{shipmentId}/customs/duties

Pay import duties and taxes for an international shipment

​path Parameters

  • shipmentId
    string
    required

​Request Body

  • paymentMethod
    string
  • paymentDetails
    object
    optional

​Responses

    • amount
      number
      optional
    • currency
      string
      optional
    • receipt
      string
      optional
Documentation

​Get shipping label

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

Get the shipping label for a shipment in various formats. Supports both JSON and XML responses. XML format follows the EDIFACT D96A standard for shipping label interchange, while JSON is provided for modern API integrations.

​path Parameters

  • shipmentId
    string
    required

​query Parameters

  • format
    string

    Label format

​Headers

  • Accept
    string

    Response format. Use application/xml for EDI-compliant responses following EDIFACT D96A standard.

​Responses

    • shipmentId
      string
    • format
      string
    • id
      string
      optional
    • url
      string
      optional
    • createdAt
      string
      optional
    • expiresAt
      string
      optional

​Get commercial invoice

GET
https://api.sh.example.com/v1
/shipments/{shipmentId}/documents/commercial-invoice

Generate a commercial invoice for an international shipment

​path Parameters

  • shipmentId
    string
    required

​query Parameters

  • format
    string

​Responses

    • url
      string
      optional
    • expiresAt
      string
      optional
Tracking & Notifications

​Get shipment tracking events

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

Retrieve detailed tracking events for a shipment

​path Parameters

  • shipmentId
    string
    required

​Responses

    • shipmentId
      string
      optional
    • events
      object[]
      optional

​Set up notifications

POST
https://api.sh.example.com/v1
/shipments/{shipmentId}/notifications

Configure notification preferences for shipment status updates

​path Parameters

  • shipmentId
    string
    required

​Request Body

  • email
    string[]
    optional
  • sms
    string[]
    optional
  • webhooks
    string[]
    optional
  • events
    string[]
    optional

​Responses

    • status
      string
      optional
    • channels
      string[]
      optional
Route Planning

​Get estimated delivery time

GET
https://api.sh.example.com/v1
/routes/{originFacilityId}/{destinationFacilityId}/{serviceLevel}/estimate

Get estimated delivery time between two facilities for a specific service level

​path Parameters

  • originFacilityId
    string
    required

    ID of the origin facility

  • destinationFacilityId
    string
    required

    ID of the destination facility

  • serviceLevel
    string
    required

    Service level for the route

​Responses

    • estimatedDeliveryTime
      object
      optional
    • distance
      object
      optional
    • route
      object
      optional