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:

graph TD
  A[Label Created] --> B[Auto-Registered] --> C[Carrier Polling] --> D[Events Normalized] --> E[Status Updated] --> F[Webhook Sent]

1. 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.
2. Auto-Registered. Shipium assigns a shipiumTrackingId and begins monitoring the shipment. For non-Shipium shipments, you register tracking manually via the Tracking Registration API.
3. 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.
4. 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.
5. Status Updated. The shipment's shipmentStatus field is updated to reflect the latest normalized event. Historical events are preserved and available via the API.
6. 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:

1. 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.
2. 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
3. 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.
4. 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.
5. 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.

Normal status progression

A typical successful delivery follows this progression:

graph LR
  A[Registered] --> B[Label Printed] --> C[In Transit] --> D[Out For Delivery] --> E[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:

graph LR
  A[Exception] --> B["Return to Sender: In Transit"] --> C["Return to Sender: Out for Delivery"] --> D["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.

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.

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.

Next steps

• Getting Started with Tracking — Set up tracking and make your first API calls.
• Shipment Tracking API — Complete API documentation
• Webhooks for Tracking — Configure automatic tracking notifications.

Resources

Your Shipium team member is available to help along the way. However, you might find these resources helpful:

• Terms and Definitions

• Troubleshooting Guide

• Contact Shipium Support