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

  • recipientAddressobject
  • senderAddressobject
  • packagesobject[]
  • idstringoptional
  • statusstringoptional
  • trackingNumberstringoptional
  • createdAtstringoptional

​Responses

    • recipientAddressobject
    • senderAddressobject
    • packagesobject[]
    • idstringoptional
    • statusstringoptional
    • trackingNumberstringoptional
    • createdAtstringoptional

​Track a shipment

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

Get the current status and tracking information for a shipment

​path Parameters

  • trackingNumberrequiredstring

​Responses

    • recipientAddressobject
    • senderAddressobject
    • packagesobject[]
    • idstringoptional
    • statusstringoptional
    • trackingNumberstringoptional
    • createdAtstringoptional

​Hold shipment

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

Place a shipment on hold at a facility

​path Parameters

  • shipmentIdrequiredstring

​Request Body

  • holdUntilstring
  • reasonstringoptional
  • facilityIdstringoptional

​Responses

    • statusstringoptional
    • holdLocationstringoptional
    • holdUntilstringoptional
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

  • shipmentIdrequiredstring

​Request Body

  • serviceLevelstring
  • insuranceobjectoptional

​Responses

    • baseRatenumberoptional
    • feesobject[]optional
    • totalRatenumberoptional
    • currencystringoptional
    • transitTimeobjectoptional

​Add insurance

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

Add or modify insurance coverage for a shipment

​path Parameters

  • shipmentIdrequiredstring

​Request Body

  • coveragenumber
  • itemsobject[]optional

​Responses

    • premiumnumberoptional
    • coveragenumberoptional
    • policyNumberstringoptional
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

  • shipmentIdrequiredstring

​Request Body

  • itemsobject[]
  • purposestringoptional
  • incotermstringoptional

​Responses

    • idstringoptional
    • statusstringoptional
    • customsValuenumberoptional
    • currencystringoptional
    • documentsobject[]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

  • shipmentIdrequiredstring

​Request Body

  • paymentMethodstring
  • paymentDetailsobjectoptional

​Responses

    • amountnumberoptional
    • currencystringoptional
    • receiptstringoptional
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

  • shipmentIdrequiredstring

​query Parameters

  • formatstring

    Label format

​Headers

  • Acceptstring

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

​Responses

    • shipmentIdstring
    • formatstring
    • idstringoptional
    • urlstringoptional
    • createdAtstringoptional
    • expiresAtstringoptional

​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

  • shipmentIdrequiredstring

​query Parameters

  • formatstring

​Responses

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

  • shipmentIdrequiredstring

​Responses

    • shipmentIdstringoptional
    • eventsobject[]optional

​Set up notifications

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

Configure notification preferences for shipment status updates

​path Parameters

  • shipmentIdrequiredstring

​Request Body

  • emailstring[]optional
  • smsstring[]optional
  • webhooksstring[]optional
  • eventsstring[]optional

​Responses

    • statusstringoptional
    • channelsstring[]optional