Skip to main content

Understanding Shipment Webhooks with Multi-Shipment Orders

Vlad-Ionut Dragan
Updated

Modern eCommerce systems rely heavily on webhooks to deliver real-time updates about order and shipment activity. One of the most important webhook types is the shipment webhook, which provides visibility into tracking progress and delivery status.

With the latest update, shipment webhooks now include all tracking activities associated with a tracking number, collected up to the moment the event is triggered. This enhancement enables more accurate tracking experiences and simplifies integrations by delivering complete tracking histories in a single payload.

 

The Challenge: Orders with Multiple Shipments

In real-world scenarios, a single order can be split into multiple shipments, each with its own tracking number and delivery timeline.

To properly support this, the webhook payload introduces a structured approach:

Key Concepts

  • All items in the order are included in the payload

  • A specific shipment event triggers the webhook

  • Items are divided into two nodes:

    • Items → contains the item(s) related to the triggering event

    • Other_Items → contains the remaining items in the order

  • Tracking activities are grouped separately under TrackingActivities

 

Payload Structure Explained

1. Items Node (Event-Specific Items)

This node contains the item(s) responsible for triggering the webhook event.

Example insight:

  • The webhook type is "Shipment Out For Delivery"

  • The item in Items has:

    • ItemShippingTracking: 889759254117

    • ItemShippingStatus: Out for Delivery

👉 This tells us:

The webhook was triggered because this specific shipment is now out for delivery.

2. Other_Items Node (Remaining Order Items)

This node includes all other items that belong to the same order but are not part of the triggering event.

Example:

  • Tracking number: 889759846468

  • Status: In Transit

👉 This shipment is still moving through the network and did not trigger the webhook.

 

3. TrackingActivities Node (Full Tracking History)

This is where the complete tracking data lives.

Each entry contains:

  • trackingNumber

  • A list of activities (scan events)

Example:

  • Tracking 889759254117 → multiple scans ending with “On FedEx vehicle for delivery”

  • Tracking 889759846468 → earlier-stage events like “Picked up”

 

How to Map Tracking Data Correctly

The most important step when working with this structure is:

✅ Match the tracking number from the item with the corresponding entry in TrackingActivities

Mapping Logic

  1. Take the tracking number from:

    • Items[].ItemShippingTracking OR

    • Other_Items[].ItemShippingTracking

  2. Find the matching object in:

    • TrackingActivities[].trackingNumber

  3. Extract the activities array for real tracking updates

 

Example Mapping

Step 1: Identify the triggering item

From Items:

ItemShippingTracking = 889759254117

Step 2: Find matching tracking activities

From TrackingActivities:

trackingNumber = 889759254117

Step 3: Use the activities

You now have access to the full tracking timeline:

  • Shipment picked up

  • Facility scans

  • Out for delivery

 

Why This Structure Matters

This design provides several key benefits:

✅ Complete Visibility

You receive all shipments and their statuses in a single webhook.

✅ Event Context

You can clearly identify which shipment triggered the webhook.

✅ Simplified Integration

No need for additional API calls to fetch tracking history.

✅ Accurate Customer Updates

You can display real-time tracking per shipment, even for split orders.

 

Best Practices for Implementation

  • Always rely on tracking number matching (not position in arrays)

  • Treat Items as the event driver, not the full dataset

  • Use TrackingActivities as the source of truth for tracking history

  • Handle multiple shipments independently in your logic

     

Webhook Payload Example



{
    "Time": 1773935769,
    "Type": "Shipment Out For Delivery",
    "CompanyName": "YourCompanyName",
    "OrderStatus": "Complete",
    "OrderStatusId": "3",
    "StoreId": "580111",
    "OrderID": "7352302371098",
    "OrderExternalOrderID": "1970",
    "OrderUrl": "https://testsore.labs.wesupply.xyz/vieworder?k=TNWtOaaACuKwwhL0x%2FTQIZmi2iCd%2BRxW8NXrp6ugx1pSAuBg%2Bl%2FsVV5AVhICKKXmHoQGfrh9iaZu%2BYuToBIpm%2BmC34F%2FBXgoa3cSG%2BHOecRPwT7Vs52EUGayXQlbqf1qhc1KNoOPHjU2ZO2gTgGonslCBJNkLDK9IGhEEZiZ5FAzGB7W4g%3D%3D",
    "ShippingTrackNo": "889759254117",
    "ShippingTrackUrl": "https://teststore.myshopify.com/apps/wesupply/track/FedEx/889759254117?orderID=shopify_7352302371098",
    "ShippingStatus": "Out for Delivery",
    "OrderPaymentType": "(For Testing) Bogus Gateway",
    "OrderCardType": "",
    "OrderCardDisplay": "",
    "OrderGiftWrapping": "",
    "OrderGiftWrappingMessage": "",
    "OrderDate": "2026-03-19T11:54:28",
    "ItemCount": 1,
    "PartiallyShipped": false,
    "OrderAmount": "158.00",
    "OrderAmountShipping": "0.00",
    "OrderAmountTax": "4.80",
    "OrderAmountCoupon": "0.00",
    "OrderAmountGiftCard": "0.00",
    "OrderAmountTotal": "162.80",
    "GrandTotalExcludingShipping": 162.8,
    "OrderCustomer": {
      "CustomerFirstName": "John",
      "CustomerLastName": "Doe",
      "CustomerEmail": "placeholder@wesupply.xyz",
      "CustomerCity": "Philadelphia",
      "CustomerStateProvince": "Pennsylvania",
      "CustomerPostalCode": "19120",
      "CustomerCountry": "United States",
      "CustomerPhone": "",
      "CustomerAddress1": "525 Adams Avenue",
      "CustomerAddress2": ""
    },
    "BillingAddress": {
      "FirstName": "John",
      "LastName": "Doe",
      "Company": "",
      "BillingEmail": "placeholder@wesupply.xyz",
      "Address1": "525 Adams Avenue",
      "Address2": "",
      "City": "Philadelphia",
      "Region": "Pennsylvania",
      "RegionCode": "",
      "Country": "United States",
      "CountryCode": "US",
      "Zip": "19120",
      "Phone": ""
    },
    "ShippingAddress": {
      "Name": "John Doe",
      "ShippingEmail": "",
      "Company": "",
      "Address1": "525 Adams Avenue ",
      "Address2": "",
      "City": "Philadelphia",
      "Region": "Pennsylvania",
      "RegionCode": "",
      "Country": "United States",
      "CountryCode": "US",
      "Zip": "19120",
      "Phone": ""
    },
    "Items": [
      {
        "ItemID": "18155094704410",
        "ItemShippingTracking": "889759254117",
        "ItemShippingService": "FedEx",
        "ItemTrackingUrl": "",
        "ItemShippingStatusId": 5,
        "ItemShippingStatus": "Out for Delivery",
        "ItemPOShipper": "FedEx",
        "ProductPartNo": "43MCHBL2",
        "ProductID": "9286143443226",
        "ProductCode": "Ayres Chambray - S",
        "ItemQuantity": 1,
        "ItemTitle": "Ayres Chambray",
        "ItemProductUri": "//teststore.myshopify.com/products/ayers-chambray",
        "ItemImageUri": "https://cdn.shopify.com/s/files/1/0868/0230/1210/files/chambray_5f232530-4331-492a-872c-81c225d6bafd.jpg?v=1714411433",
        "ItemPrice": "60.00",
        "ItemTax": "4.8000",
        "ItemDiscountDetailsTotal": "0.0000",
        "ItemLength": "",
        "ItemWidth": "",
        "ItemHeight": "",
        "ItemWeight": "",
        "ItemMeasureUnit": "",
        "ItemWeightUnit": "",
        "ItemStatus": "Shipped",
        "ItemStatusId": "3",
        "ItemLevelSupplierName": 97271152922,
        "EstimatedPackageDelivery": "19.03.2026",
        "NotUpdatedSince": "19 Mar. 26 13:48:00",
        "ItemDownloadUrl": "",
        "ItemOptions": {
          "Size": "S"
        },
        "ItemPriceWithTax": 64.8,
        "ItemSubtotal": 60,
        "ItemDiscountedSubtotal": 60,
        "ItemCost": "",
        "Item_CouponAmount": "",
        "ItemGiftWrap": false,
        "ItemGiftMessage": ""
      }
    ],
    "Other_Items": [
      {
        "ItemID": "18155094671642",
        "ItemShippingTracking": "889759846468",
        "ItemShippingService": "Other",
        "ItemTrackingUrl": "",
        "ItemShippingStatusId": 2,
        "ItemShippingStatus": "In Transit",
        "ItemPOShipper": "Other",
        "ProductPartNo": "43WPLBR1",
        "ProductID": "9286140723482",
        "ProductCode": "Cydney Plaid - XS",
        "ItemQuantity": 1,
        "ItemTitle": "Cydney Plaid",
        "ItemProductUri": "//teststore.myshopify.com/products/cydney-plaid",
        "ItemImageUri": "https://cdn.shopify.com/s/files/1/0868/0230/1210/files/DaveChristine65_SiteSquare.jpg?v=1714411408",
        "ItemPrice": "98.00",
        "ItemTax": "0.0000",
        "ItemDiscountDetailsTotal": "0.0000",
        "ItemLength": "",
        "ItemWidth": "",
        "ItemHeight": "",
        "ItemWeight": "1",
        "ItemMeasureUnit": "",
        "ItemWeightUnit": "lb",
        "ItemStatus": "Shipped",
        "ItemStatusId": "3",
        "ItemLevelSupplierName": 96852345114,
        "EstimatedPackageDelivery": "24.03.2026",
        "NotUpdatedSince": "19 Mar. 26 07:30:00",
        "ItemDownloadUrl": "",
        "ItemOptions": {
          "Size": "XS"
        },
        "ItemPriceWithTax": 98,
        "ItemSubtotal": 98,
        "ItemDiscountedSubtotal": 98,
        "ItemCost": "",
        "Item_CouponAmount": "",
        "ItemGiftWrap": false,
        "ItemGiftMessage": ""
      }
    ],
    "TrackingActivities": [
      {
        "trackingNumber": "889759846468",
        "activities": [
          {
            "location": "Bell, CA, US",
            "timestamp": "2026-03-19T00:16:00Z",
            "description": "Picked up"
          },
          {
            "location": "US",
            "timestamp": "2026-03-19T00:17:00Z",
            "description": "Shipment information sent to FedEx"
          },
          {
            "location": "SANTA FE SPRINGS, CA, US",
            "timestamp": "2026-03-19T02:45:00Z",
            "description": "Arrived at FedEx location"
          },
          {
            "location": "SANTA FE SPRINGS, CA, US",
            "timestamp": "2026-03-19T02:46:00Z",
            "description": "Shipment arriving On-Time"
          },
          {
            "location": "SANTA FE SPRINGS, CA, US",
            "timestamp": "2026-03-19T07:30:00Z",
            "description": "Left FedEx origin facility"
          }
        ]
      },
      {
        "trackingNumber": "889759254117",
        "activities": [
          {
            "location": "Los Angeles, CA, US",
            "timestamp": "2026-03-18T23:32:00Z",
            "description": "Shipment information sent to FedEx"
          },
          {
            "location": "CARSON, CA, US",
            "timestamp": "2026-03-19T00:48:00Z",
            "description": "Picked up"
          },
          {
            "location": "CARSON, CA, US",
            "timestamp": "2026-03-19T04:15:00Z",
            "description": "Arrived at FedEx location"
          },
          {
            "location": "CARSON, CA, US",
            "timestamp": "2026-03-19T04:17:00Z",
            "description": "Shipment arriving On-Time"
          },
          {
            "location": "CARSON, CA, US",
            "timestamp": "2026-03-19T05:08:00Z",
            "description": "Arrived at FedEx location"
          },
          {
            "location": "CARSON, CA, US",
            "timestamp": "2026-03-19T07:04:00Z",
            "description": "Departed FedEx location"
          },
          {
            "location": "BLOOMINGTON, CA, US",
            "timestamp": "2026-03-19T09:36:00Z",
            "description": "Arrived at FedEx location"
          },
          {
            "location": "BLOOMINGTON, CA, US",
            "timestamp": "2026-03-19T10:57:00Z",
            "description": "Departed FedEx location"
          },
          {
            "location": "FULLERTON, CA, US",
            "timestamp": "2026-03-19T13:41:00Z",
            "description": "At local FedEx facility"
          },
          {
            "location": "FULLERTON, CA, US",
            "timestamp": "2026-03-19T13:48:00Z",
            "description": "On FedEx vehicle for delivery"
          }
        ]
      }
    ],
    "ReturnReference": "",
    "ReturnData": [],
    "CurrencyCode": "USD",
    "StoreDomain": "",
    "CartProvider": "Shopify",
    "HasShippingInsurance": false,
    "ShippingInsuranceCost": "0.00"
  }

Summary

When dealing with multi-shipment orders:

  • The webhook includes all order items

  • The triggering shipment is found in Items

  • The rest are in Other_Items

  • TrackingActivities contains the real tracking data

  • You must map tracking numbers to retrieve the correct activity stream

This structure ensures that your integration remains accurate, scalable, and aligned with real-world shipping scenarios.

Related articles

Comments

0 comments

Please sign in to leave a comment.