An order with three parcels can be partly delivered even while its latest parcel is still pending. A single status copied from the most recently updated shipment hides that reality. Model the order as a group of shipment cycles and preserve each parcel’s own evidence.
The customer needs to know which items are in each parcel, what has arrived and what still needs attention. The tracking API supplies shipment observations; your fulfillment system supplies the item-to-parcel mapping. Do not infer that mapping from a carrier description.
Separate order identity from shipment identity
Create one owned shipment record per parcel cycle and store the Trace record ID alongside your fulfillment ID. Use the same order_id to group records, but give every parcel creation its own stable idempotency key. If a replacement ships later, create a new cycle instead of overwriting the original tracking identity.
| Entity | Responsibility |
|---|---|
| Order | Buyer ownership and the purchased items. |
| Fulfillment | Which items and quantities belong to this shipment. |
| Shipment cycle | Carrier, number, verified events and monitoring state. |
| Order summary | A derived view of all expected parcels, including those without scans. |
Derive a summary that does not hide unfinished work
Count all expected parcels, not only the ones that already have tracking events. Use “2 of 3 parcels delivered” when two are delivered. Keep an exception visible even if another parcel arrived. A return journey should be displayed separately from outbound delivery.
Illustrative view model · statuses from authorized stored records
function parcelSummary(parcels) {
if (parcels.length === 0) return "No parcels assigned yet";
const delivered = parcels.filter(p => p.status === "delivered").length;
const attention = parcels.some(p => p.status === "exception");
return `${delivered} of ${parcels.length} parcels delivered` +
(attention ? " · a parcel needs attention" : "");
}Give each parcel a stable place in the interface
Use a stable fulfillment order rather than reordering cards whenever a webhook arrives. Show a parcel label, its assigned items, current status, last verified time and an expandable scan history. Preserve missing location and estimate fields instead of filling them with another parcel’s values.
Trace UI includes components for order and shipment experiences. Feed them an authorized view model and use the timeline builder to preview difficult states. A UI preview is illustrative and does not retrieve real carrier events.
Test combinations rather than only the all-delivered case
Use a three-parcel fixture with one delivered, one in transit and one awaiting its first scan. Then add an exception, a delayed webhook and a replacement cycle. Verify that the order summary updates without losing parcel details or announcing the whole order as delivered prematurely.
Common questions
Does a delivered parcel mean the whole order is delivered?
Only when every expected outbound parcel is delivered according to your fulfillment model. A shipment event alone cannot establish that all ordered items have arrived.
References & next steps
Implementation details were checked against Trace’s current API. External product details may change; verify the linked documentation before deciding.