How Tracking Works

About Track and Trace

Shipium's Track and Trace service provides a single, unified interface for tracking shipments across 65+ carriers. Rather than integrating with each carrier's tracking API individually, you integrate once with Shipium and receive normalized, consistent tracking data regardless of which carrier handles the package.

This page explains the concepts and architecture behind Shipium's tracking system.

Tracking lifecycle

Every shipment tracked through Shipium follows this lifecycle:

Label Created
Auto-Registered
Carrier Polling
Events Normalized
Status Updated
Webhook Sent

Label Created. When a shipment label is generated through Shipium's Carrier and Method Selection service, tracking is automatically registered. No additional setup is needed.
Auto-Registered. Shipium assigns a shipiumTrackingId and begins monitoring the shipment. For non-Shipium shipments, you register tracking manually via the Tracking Registration API.
Carrier Polling. Shipium periodically polls the carrier's tracking systems for updates. For carriers that support push notifications (webhooks from the carrier to Shipium), updates arrive in near-real-time.
Events Normalized. Raw carrier-specific tracking data is transformed into Shipium's standardized format. Status codes, location data, timestamps, and event descriptions are all normalized so you get a consistent data model regardless of carrier.
Status Updated. The shipment's shipmentStatus field is updated to reflect the latest normalized event. Historical events are preserved and available via the API.
Webhook Sent. If you have registered a tracking webhook, Shipium sends an HTTP POST to your endpoint containing the full tracking event history for the updated shipment.

How Shipium collects tracking data

Shipium maintains integrations with 65+ carriers. The method of data collection varies by carrier:

Polling (most carriers). Shipium periodically queries the carrier's tracking API for status updates. Polling frequency varies based on shipment age and status but is designed to balance freshness with carrier rate limits.
Push / Carrier webhooks (select carriers). Some carriers support webhook subscriptions where the carrier proactively sends tracking updates to Shipium. This results in faster update times compared to polling.

In both cases, the raw carrier response goes through Shipium's normalization pipeline, which:

Maps carrier-specific status codes to Shipium's standardized shipment statuses
Parses and normalizes location data (city, region, postal code, country)
Converts timestamps to consistent formats with timezone information
Extracts estimated delivery dates when provided by the carrier

The normalization pipeline

When raw tracking data arrives from a carrier (whether via polling or push), it goes through a multi-step normalization pipeline:

Status mapping. Carrier-specific status codes (e.g., FedEx's "AA" for "At Airport") are mapped to one of Shipium's 10 standardized shipment statuses. Shipium maintains mapping tables for each carrier, updated as carriers change their status codes.
Location standardization. Event locations are parsed and normalized. This includes:
- Extracting city, region, postal code, and country from various carrier formats
- Inferring country codes from postal code patterns when not explicitly provided
- Normalizing timezone abbreviations (e.g., EST → America/New_York) for accurate timestamp conversion
Timestamp processing. Event timestamps are converted to consistent ISO 8601 format with timezone information. Shipium handles carrier-specific date formats and resolves timezone ambiguities using event location data.
Estimated delivery date extraction. When the carrier provides an estimated delivery date, Shipium captures both the current estimate and preserves the original estimate for performance analysis.
Event deduplication and ordering. Events are ordered chronologically, and duplicate events (same status, time, and location) are consolidated.

This pipeline ensures that regardless of whether a shipment travels via a major carrier, a regional carrier, or an international service, you receive consistently structured tracking data.

Tracking data availability by carrier

While all carriers in Shipium's network support tracking, the depth of data available varies by carrier:

Carrier estimated delivery date. Not all carriers provide an estimated delivery date. When unavailable, the carrierEstimatedDeliveryDate and originalCarrierEstimatedDeliveryDate fields in the tracking response will be null.
Location detail. Some carriers provide full location information (city, region, postal code, country) for every event, while others provide partial location data or none at all.
Event granularity. Major carriers (FedEx, UPS, USPS, DHL) typically provide detailed scan events at each facility. Smaller regional carriers may provide fewer intermediate events.
Update frequency. Some carriers proactively push tracking updates to Shipium as events occur, resulting in near-real-time updates. Others are polled periodically, with frequency varying based on shipment age and status.

For a complete list of supported carriers and their carrierId values, see Supported Carriers.

Shipment statuses

Shipium normalizes all carrier-specific status codes into 10 standard shipment statuses. These statuses represent the public-facing lifecycle of a package.

Status	Description
Registered	The shipment has been registered for tracking. Shipium is aware of the package but has not yet received tracking data from the carrier.
Label Printed	The carrier has received shipment information, and a label has been created. The package has not yet been picked up or scanned.
In Transit	The package is in the carrier's possession and moving through the delivery network. This includes pickup, facility arrivals, facility departures, and general in-transit scans.
Out For Delivery	The package is on a delivery vehicle and out for final delivery to the recipient.
Delivered	The package has been delivered to the recipient.
Exception	The carrier has flagged an exception for this package (e.g., address issue, damage, weather delay, failed delivery attempt).
Return to Sender: In Transit	The package is being returned to the sender and is currently in transit through the carrier network.
Return to Sender: Exception	The package is being returned to the sender, and there has been a carrier exception during the return.
Return to Sender: Out for Delivery	The package is being returned and is out for delivery to the return address.
Return to Sender: Delivered	The returned package has been delivered back to the sender.

Normal status progression

A typical successful delivery follows this progression:

Registered
Label Printed
In Transit
Out For Delivery
Delivered

Not every shipment goes through every status. Some carriers skip Label Printed and go directly from Registered to In Transit once the first scan occurs.

Exception and return-to-sender flows

When a carrier flags an issue, the status transitions to Exception. An exception does not necessarily mean the package is lost; it may be a temporary delay (weather, address clarification) after which the shipment resumes normal progression.

If the carrier initiates a return, the shipment enters the return-to-sender flow:

Exception
Return to Sender: In Transit
Return to Sender: Out for Delivery
Return to Sender: Delivered

Backward status changes

In rare cases, a shipment's status may appear to move backward (e.g., from Out For Delivery back to In Transit). This can happen when:

A delivery attempt fails and the package returns to a carrier facility
The carrier corrects previously reported data
A different carrier leg takes over (e.g., for multi-carrier shipments)

These transitions reflect actual carrier-reported events and are not errors.

Tracking events

Each tracking update from the carrier is stored as an individual tracking event. Events contain the following fields.

Field	Description
`carrierDescription`	The carrier's original description of the event
`shipmentStatus`	The normalized Shipium shipment status for this event
`eventDate`	Timestamp of the event (ISO 8601 format)
`city`	City where the event occurred
`region`	State/province/region where the event occurred
`postalCode`	Postal code where the event occurred
`country`	Country code where the event occurred

By default, the Shipment Tracking API returns only the most recent event. To retrieve the full event history for a shipment, set the excludeEvents query parameter to false. See the Shipment Tracking API documentation for details.

Tracking identifiers

Shipium uses several identifiers to reference shipments. Understanding which identifier to use is important when querying the API.

Identifier	Format	Description	When to use
`shipiumTrackingId`	UUID (e.g., `7a41e741-4cc2-48d6-a3a2-5dc565a378de`)	Shipium's unique identifier assigned when tracking is registered. Every tracked shipment has one.	Preferred identifier for API lookups when you have it. Always returned in registration and tracking responses.
`carrierTrackingId`	Carrier-specific (e.g., `1Z9F0901YW17975733`)	The tracking number assigned by the carrier. Used with `carrierId` for lookups.	Use when you have the carrier's tracking number and carrier name but not the Shipium tracking ID.
`carrierId`	String (e.g., `ups`, `fedex`, `usps-direct`)	Identifies which carrier handles the shipment. Required with `carrierTrackingId` for carrier-based lookups.	Always paired with `carrierTrackingId`. See Supported Carriers for valid values.
`partnerShipmentId`	Your custom ID (e.g., `ORDER-12345`)	An optional identifier you provide during registration or label creation that maps to your internal systems	Use for bulk lookups by your own IDs via the bulk partner shipment ID search endpoint.

Carrier estimated delivery dates

The tracking response includes two estimated delivery date fields:

carrierEstimatedDeliveryDate. The carrier's current estimated delivery date. This value may change over time as the carrier updates its estimate based on actual transit progress.
originalCarrierEstimatedDeliveryDate. The carrier's initial estimated delivery date, captured at the time of the first tracking update. This value does not change and serves as a baseline for delivery performance analysis.

Not all carriers provide estimated delivery dates. When unavailable, these fields are null.

How webhooks fit in

Rather than polling the Shipment Tracking API to check for updates, you can register a webhook to receive automatic notifications when tracking events occur. When a shipment's tracking data is updated, Shipium sends an HTTP POST request to your configured endpoint with the full event history.

Webhooks are registered through the Shipium Console and can be filtered by event type. For complete setup instructions and payload details, see Webhooks for Tracking.

Tracking in the Shipium Console

The Shipium Partner Console provides a web interface for tracking shipments:

Search. Look up shipments by Shipium tracking ID, carrier tracking ID, or partner shipment ID. Bulk search supports up to 100 IDs at a time.
Timeline view. View the full event history for a shipment in a visual timeline.
CSV export. Export tracking data for analysis.

The Console is useful for customer service teams, operations monitoring, and ad hoc investigations. For programmatic access, use the Shipment Tracking API.