Tracking Troubleshooting Guide

About this guide

This guide answers frequently asked questions about Track and Trace behavior and walks you through verifying your integration, understanding status transitions, and resolving unexpected results.

Verify your integration

Before investigating specific issues, confirm your integration is working with this 4-step checklist:

Step 1. Ping

Verify connectivity and authentication:

curl -s https://api.shipium.com/api/v1/tracking/ping \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Expected: { "status": 1, "info": "pong" }

If this fails, the issue is authentication or network connectivity — not tracking-specific.

Step 2. Single lookup

Look up a known shipment to verify tracking data retrieval.

By Shipium tracking ID:

curl -s "https://api.shipium.com/api/v1/tracking/{shipiumTrackingId}?excludeEvents=false" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

By carrier tracking ID:

curl -s "https://api.shipium.com/api/v1/tracking/carrier/{carrierId}/{carrierTrackingId}?excludeEvents=false" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Expected: A tracking response with shipment status and events

Step 3. Webhook endpoint

If using webhooks, verify your endpoint is reachable:

  1. Go to Tracking > Webhooks in the Shipium Console.
  2. Send a test event to your endpoint.
  3. Verify your endpoint received and acknowledged the request with a 2xx response.

Step 4. Events endpoint

Verify the shipment events endpoint returns data in webhook format:

curl -s "https://api.shipium.com/api/v1/deliveryexperience/shipment/{shipmentId}/events?eventTypes=tracking_updated" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Expected: An events array with tracking_updated entries

Frequently asked questions

"I just created a label, but there's no tracking data"

Cause: This is normal. After label creation, the shipment status is Registered or Label Printed. Tracking events from the carrier don't appear until the carrier scans the package (usually when it's picked up or dropped off).

What to expect:

Timeline: Depending on the carrier, this can take a few hours to 1–2 business days after the package enters the carrier's network.

Action: Wait for the carrier to scan the package. If no updates appear after 48 hours and the package has been tendered to the carrier, contact your Shipium team member.

"Shipment is stuck on Label Printed"

Cause: The carrier has received the shipment information but has not yet scanned the package.

Possible reasons:

Action:

  1. Confirm the package was physically handed to the carrier.
  2. Check the carrier's own tracking page using the carrierTrackingLink from the API response.
  3. If the carrier's page also shows no movement, the issue is on the carrier side.
  4. If the carrier's page shows movement but Shipium doesn't, contact your Shipium team member.

"Webhook not firing"

Cause: Several potential issues:

Check What to look for
Webhook status Is the webhook active in the Console, or has it been marked "broken"?
Endpoint URL Is the URL correct and publicly accessible from the internet?
SSL certificate Is your certificate valid and from a trusted Certificate Authority (CA)?
Authentication If using custom headers, are the credentials correct?
Event types Is tracking_updated selected?
Firewall Does your firewall allow inbound HTTPS from Shipium's IP ranges?

Action:

  1. Check the webhook status in Tracking > Webhooks in the Console.
  2. Send a test event from the Console to verify endpoint connectivity.
  3. If the webhook is marked "broken," fix the underlying endpoint issue, then contact Shipium support to reset it.
  4. If testing with a new endpoint, try webhook.site first to rule out endpoint-side issues.

"Bulk search returns empty"

Cause: None of the provided IDs matched registered shipments.

Common reasons:

Action:

  1. Verify you're using the correct endpoint for your ID type.
  2. Test with a single ID that you know works before troubleshooting the bulk request.
  3. For non-Shipium shipments, confirm they've been registered.

"Getting 404 on tracking lookup"

Cause: The tracking ID was not found in Shipium's system.

Possible reasons:

Action:

  1. Double-check the ID value for typos.
  2. If using a carrier lookup, verify the carrierId string is valid — an unrecognized carrierId returns a 400 Bad Request, not a 404. A 404 means the carrierId is valid but no shipment with that carrierTrackingId is registered under it. See Supported Carriers for valid carrierId values.
  3. For non-Shipium shipments, register them first via the Tracking Registration API.
  4. Search by an alternative ID (e.g., if the Shipium ID fails, try the carrier ID, or vice versa).

"Getting 401 or 403 errors"

401 Unauthorized:

Your OAuth token has expired. Action: Obtain a fresh access token and retry.

403 Forbidden:

Your OAuth client lacks the required scopes for tracking. Action: Contact your Shipium team member to verify your OAuth client configuration.

"Tracking status seems wrong or out of order"

Cause: Shipium normalizes carrier-specific statuses into 10 standard values. Occasionally:

Action:

  1. Check the full event history (set excludeEvents=false) to see all events in chronological order.
  2. Compare with the carrier's own tracking page using carrierTrackingLink.
  3. If there's a persistent discrepancy, contact your Shipium team member with the tracking ID.

Status transition reference

Normal forward progression

Registered
Label Printed
In Transit
Out For Delivery
Delivered

Exception flow

Any status
Exception
Normal flow resumes
Return to Sender flow

An Exception status doesn't always mean the package is lost. Common exceptions include:

After the exception is resolved, the shipment may resume its normal flow.

Return to Sender (RTS) flow

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

RTS is initiated by the carrier when a package cannot be delivered. Not all RTS shipments go through every status.

Statuses that may appear to go "backward"

In some situations, a shipment's status may appear to move backward. This is normal behavior that reflects how carriers report and occasionally correct tracking data — not an error in Shipium. The most common cases are explained below.

Transition Explanation
Out For Delivery → In Transit Delivery attempt failed; package returned to facility
In Transit → Label Printed Carrier corrected earlier scan data
Delivered → Exception Extremely rare; carrier corrected delivery status (e.g., delivered to wrong address)

These transitions reflect actual carrier data and are not Shipium errors.

Error codes reference and common failure causes

HTTP Status Meaning Common causes Action
200 Success Request processed successfully —
400 Bad Request Malformed JSON, invalid carrier ID, more than 100 IDs in bulk, tracking ID format invalid Fix the request and retry.
401 Unauthorized OAuth token expired or invalid Refresh token and retry.
403 Forbidden Missing OAuth scopes, invalid client credentials Contact Shipium to verify OAuth setup.
404 Not Found Tracking ID not registered, typo in ID Verify ID; register if needed.
5xx Server Error Temporary Shipium or carrier issue Retry with exponential backoff (1s, 2s, 4s). If persistent, contact support.

Getting help

If you've worked through this guide and still need assistance:

  1. Gather the following information.

    • The tracking ID(s) affected (Shipium tracking ID, carrier tracking ID, or both)
    • The API endpoint you're calling and the full response (including HTTP status code)
    • The approximate time the issue started
    • Whether the issue affects all shipments or specific ones

  2. Contact your Shipium team member or reach out to Shipium Support.

  3. For webhook issues, also include:

    • Your webhook endpoint URL
    • Any error logs from your endpoint
    • The webhook status shown in the Shipium Console

Updated 4 months ago