MasonHub ERP Integration home pagelight logo
  1. Shipments
  2. Get Order Shipments
GET
/shipments
curl --request GET \
     --url https://sandbox.masonhub.co/dragonfly-cosmetics-demo/api/v1/shipments \
     --header 'Authorization: Bearer <token>'

The Shipments API provides access to outbound shipment information for orders that have been fulfilled and shipped from MasonHub distribution centers. This endpoint allows you to track shipments, retrieve tracking numbers, and monitor multi-shipment orders.

Orders can ship in multiple packages when items are too large for a single package, ship from different locations, or when inventory availability requires splits.

​
Query Parameters

id
UUID[]

MasonHub shipment UUIDs. Supports batching 1-30 IDs per request.

coid
string[]

Customer order IDs. Filter shipments by customer order identifiers.

sdt
string

Start date/time in RFC3339 format (e.g., 2018-08-01T00:00:00Z). Filters shipments from this date onwards.

edt
string

End date/time in RFC3339 format. Filters shipments up to this date.

offset
default:0
integer

Pagination offset for retrieving subsequent pages of results.

limit
default:30
integer

Number of results to return. Range: 1-100.

curl -X GET "https://app.masonhub.co/{account}/api/v1/shipments?coid=12345,67890&sdt=2018-08-01T00:00:00Z" \
  -H "Authorization: Bearer your_jwt_token"

{
  "search_criteria": {
    "sdt": "2018-08-01T00:00:00Z",
    "edt": null
  },
  "limit": 30,
  "offset": 0,
  "list_type": "detail",
  "include_counts": false,
  "data": [
    {
      "id": "db79huy5-ec61-7892-ae7b-57a563b68133",
      "shipment_id": "f0h7uuk",
      "customer_order_id": "12345",
      "shipping_provider": "UPS",
      "shipper_service_level": "ground",
      "tracking_number": "1z324897234nferg45",
      "tracking_url": "http://ups.com/tracking/1z324897234nferg45",
      "shipment_date_time": "2018-08-06T15:11:19Z",
      "shipment_line_items": [
        {
          "sku_customer_id": "shirts872340",
          "quantity": 2
        },
        {
          "sku_customer_id": "pants3422",
          "quantity": 1
        }
      ]
    }
  ]
}

​
Response Fields

​
Core Shipment Fields

id
string

MasonHub internal UUID for the shipment

shipment_id
string

Human-readable shipment identifier

customer_order_id
string

Customer’s order identifier

shipping_provider
string

Carrier name (UPS, USPS, FedEx, etc.)

shipper_service_level
string

Service level (ground, priority, express)

tracking_number
string

Carrier tracking number

tracking_url
string

Direct tracking URL to carrier’s tracking page

shipment_date_time
string

Ship date and time in RFC3339 format

shipment_line_items
array

Array of line items included in this shipment. Each item contains:

  • sku_customer_id (string): Customer SKU identifier
  • quantity (integer): Quantity of this SKU in the shipment

​
Multi-Shipment Orders

Orders can ship in multiple packages. When querying by customer_order_id, you may receive multiple shipments for the same order:

{
  "data": [
    {
      "shipment_id": "f0h7uuk",
      "customer_order_id": "12345",
      "shipping_provider": "UPS",
      "tracking_number": "1z324897234nferg45",
      "shipment_line_items": [
        {
          "sku_customer_id": "shirts872340",
          "quantity": 2
        }
      ]
    },
    {
      "shipment_id": "u3d88z4",
      "customer_order_id": "12345",
      "shipping_provider": "UPS",
      "tracking_number": "1z987654321abcdef",
      "shipment_line_items": [
        {
          "sku_customer_id": "pants3422",
          "quantity": 1
        }
      ]
    }
  ]
}

Always handle the possibility of multiple shipments per order in your integration code.

​
Integration with Orders API

Shipment information is also included in the Orders API response for fulfilled orders:

GET /orders?status=fulfilled

The order response will include a shipments array with the same shipment data structure.

​
Carrier Tracking URLs

MasonHub provides direct tracking URLs for major carriers:

UPS

http://ups.com/tracking/{tracking_number}

USPS

http://usps.gov/tracking/{tracking_number}

FedEx

https://www.fedex.com/apps/fedextrack/index.html?action=track&tracknumbers={tracking_number}

​
Use Cases

​
Customer Notifications

  • Send shipping confirmation emails
  • Provide tracking information
  • Update order status on customer portals
  • Generate shipping notifications

​
Business Intelligence

  • Track shipment volumes by carrier
  • Monitor average ship times
  • Analyze multi-shipment rates
  • Evaluate carrier performance

​
Inventory Planning

  • Demand forecasting
  • Inventory allocation optimization
  • Shipping cost analysis
  • Carrier selection strategies

​
Best Practices

Real-time Updates

Use orderEvent callbacks for immediate shipment notifications instead of polling.

Multi-shipment Handling

Always handle the possibility of multiple shipments per order.

Tracking Integration

Provide customers with direct tracking links for better experience.

Date Range Queries

Use date ranges (sdt and edt) for efficient historical data retrieval.