​

Shipment Tracking API

The Shipments API provides comprehensive access to outbound shipment information for orders that have been fulfilled and shipped from MasonHub distribution centers. Track packages, manage customer notifications, and analyze shipping performance.

​

Core Operations

​

Get Shipments

Retrieve detailed shipment information for fulfilled orders.

​

Query Parameters

​

Shipment Data Structure

​

Core Fields

​

Line Item Details

Each shipment contains detailed line item information:

• Basic Line Items
• Enhanced Line Items

{
  "shipment_line_items": [
    {
      "sku_customer_id": "shirts872340",
      "quantity": 2
    },
    {
      "sku_customer_id": "pants3422",
      "quantity": 1
    }
  ]
}

​

Multi-Shipment Orders

Orders frequently ship in multiple packages due to:

​

Multi-Shipment Example

​

Carrier Integration

​

Supported Carriers

​

Tracking URLs

MasonHub provides direct tracking URLs for immediate customer access:

{
  "tracking_number": "1z324897234nferg45",
  "tracking_url": "http://ups.com/tracking/1z324897234nferg45",
  "mobile_tracking_url": "http://m.ups.com/tracking/1z324897234nferg45",
  "carrier_app_link": "ups://track/1z324897234nferg45"
}

​

Event Integration

​

Order Fulfillment Callbacks

Receive orderEvent callbacks when orders ship:

​

Delivery Confirmation

Some carriers provide delivery confirmation callbacks:

{
  "callback_url": "https://client.com/api/delivery_event",
  "message_type": "deliveryEvent",
  "message_id": "f79881fe-e65c-48g1-d82c-590c1d97cgcg",
  "data": {
    "shipment_id": "88888",
    "tracking_number": "1z324897234nferg45",
    "delivery_status": "delivered",
    "delivery_date_time": "2018-08-09T14:32:00Z",
    "delivery_location": "Front Door",
    "signature_required": false,
    "signed_by": null
  }
}

​

Customer Notifications

​

Shipping Confirmation

Use shipment data to create comprehensive shipping notifications:

• Email Template
• SMS Template
• App Notification

<h2>Your Order Has Shipped!</h2>
<p>Order #{{customer_order_id}} has been shipped via {{shipping_provider}}.</p>

<h3>Tracking Information</h3>
<p>Tracking Number: <strong>{{tracking_number}}</strong></p>
<p><a href="{{tracking_url}}">Track Your Package</a></p>

<h3>Shipped Items</h3>
{{#each shipment_line_items}}
<p>{{sku_customer_id}} - Quantity: {{quantity}}</p>
{{/each}}

<p>Estimated Delivery: {{estimated_delivery}}</p>

​

Analytics & Reporting

​

Shipping Metrics

Track key performance indicators:

​

Sample Analytics Query

// Analyze shipping performance by carrier
function analyzeCarrierPerformance(shipments) {
  const carrierStats = {};
  
  shipments.forEach(shipment => {
    const carrier = shipment.shipping_provider;
    
    if (!carrierStats[carrier]) {
      carrierStats[carrier] = {
        totalShipments: 0,
        onTimeDeliveries: 0,
        averageTransitTime: 0
      };
    }
    
    carrierStats[carrier].totalShipments++;
    
    // Calculate on-time delivery
    if (shipment.actual_delivery <= shipment.estimated_delivery) {
      carrierStats[carrier].onTimeDeliveries++;
    }
  });
  
  return carrierStats;
}

​

Advanced Features

​

Package Optimization

​

Special Handling

Track special handling requirements:

{
  "special_handling": {
    "fragile": true,
    "signature_required": true,
    "adult_signature": false,
    "delivery_confirmation": true,
    "insurance_value": 500.00,
    "temperature_controlled": false
  }
}

​

Best Practices

​

Integration Tips

1. Callback Processing: Design fast callback handlers for shipment events
2. Data Storage: Store shipment data for customer service and analytics
3. Tracking Integration: Provide direct tracking links in customer communications
4. Mobile Optimization: Ensure tracking links work well on mobile devices

​

Error Handling

Common scenarios and solutions:

​

Next Steps

After implementing shipment tracking, explore:

• Order Management for order lifecycle management
• Inventory Management for stock tracking
• Callback Configuration for event handling setup