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 eventOther_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
Itemshas:ItemShippingTracking: 889759254117ItemShippingStatus: 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:
trackingNumberA 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
Take the tracking number from:
Items[].ItemShippingTrackingOROther_Items[].ItemShippingTracking
Find the matching object in:
TrackingActivities[].trackingNumber
Extract the
activitiesarray 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
Itemsas the event driver, not the full datasetUse
TrackingActivitiesas the source of truth for tracking historyHandle 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
ItemsThe rest are in
Other_ItemsTrackingActivities 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.
Comments
0 comments
Please sign in to leave a comment.