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:

• Immediately after label creation: Status is Registered.
• After carrier receives shipment info: Status changes to Label Printed.
• After first physical scan: Status changes to In Transit.

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:

• Package hasn't been dropped off or picked up yet.
• Carrier experienced a delay in scanning.
• The tracking number was created, but the shipment was never actually tendered to the carrier.

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:

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:

• Typos in tracking IDs or carrier IDs
• Shipments haven't been registered (non-Shipium shipments must be registered via the Tracking Registration API).
• Using the wrong ID type (e.g., passing carrier tracking IDs to the Shipium tracking ID endpoint)
• Partner shipment IDs have expired (retained for 100 days).

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:

• The shipment hasn't been registered for tracking.
• Typo in the tracking ID
• The shipiumTrackingId or carrierTrackingId doesn't match any registered shipment.
• For carrier lookups: the carrierId doesn't match the carrier that was registered.

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:

• A carrier corrects previously reported data.
• Events arrive out of order from the carrier.
• Multi-carrier shipments show transitions that seem backward.

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

graph LR
  A[Registered] --> B[Label Printed] --> C[In Transit] --> D[Out For Delivery] --> E[Delivered]

Exception flow

graph LR
  A[Any status] --> B[Exception] --> C[Normal flow resumes]
  B --> D[Return to Sender flow]

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

• Failed delivery attempt (will retry)
• Address issue (package held for clarification)
• Weather delay (temporary hold)
• Customs hold (international shipments)

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

Return to Sender (RTS) flow

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

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

Error codes reference and common failure causes

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