How to get started with tracking

This guide walks you through integrating with Shipium's Track and Trace service. By the end, you'll be able to track shipments via the API, register non-Shipium shipments, and receive webhook notifications.

Prerequisites

Before you begin, make sure you have the following:

1. Shipium API credentials. An OAuth client ID and client secret provided by your Shipium team member
2. OAuth token. All tracking API calls require a Bearer token obtained via OAuth. See Shipium's authentication documentation for details on acquiring a token.
3. Network access. Ensure your systems can reach https://api.shipium.com over HTTPS.

Obtain an access token

Request an OAuth token using your client credentials:

curl -s -X POST https://auth.shipium.com/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=$CLIENT_ID&client_secret=$CLIENT_SECRET&audience=https://api.shipium.com"

The response contains an access_token field. Use this token in the Authorization header for all subsequent API calls:

export ACCESS_TOKEN="your-access-token-here"

Note: Tokens expire after a period defined by your OAuth configuration. Implement token refresh logic in your integration to handle expiration gracefully.

Verify your credentials with ping

The ping endpoint confirms your credentials and connectivity are working.

Example cURL call:

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

Example JSON response:

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

If you receive a 403 response, check that your OAuth token is valid and has the required scopes.

Track Shipium-labeled shipments

Shipments created through Shipium's Carrier and Method Selection service are automatically registered for tracking. You do not need to call any registration endpoint. As soon as a label is generated, Shipium begins monitoring the shipment. For full details, refer to Shipment Tracking API.

Look up a single shipment by Shipium tracking ID

Required path element: shipiumTrackingId — Replace with the UUID returned when the shipment was created (e.g., 7a41e741-4cc2-48d6-a3a2-5dc565a378de).

Optional query parameter: excludeEvents — Set to false to include the full event history. The default (true) returns only the most recent status without individual events.

Example cURL call:

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

Example JSON response:

{
  "shipiumTrackingId": "7a41e741-4cc2-48d6-a3a2-5dc565a378de",
  "shipiumShipmentId": "a1234567-89ab-cdef-0123-456789abcdef",
  "carrierId": "ups",
  "carrierTrackingId": "1Z9F0901YW17975733",
  "carrierServiceMethodId": "ups-ground-service-method",
  "shipmentStatus": "In Transit",
  "shippedDateTime": "2026-03-10T14:30:00Z",
  "carrierEstimatedDeliveryDate": "2026-03-15T23:00:00Z",
  "originalCarrierEstimatedDeliveryDate": "2026-03-15T23:00:00Z",
  "carrierTrackingLink": "https://www.ups.com/track?tracknum=1Z9F0901YW17975733",
  "trackingEvents": [
    {
      "carrierDescription": "Departed Facility",
      "shipmentStatus": "In Transit",
      "eventDate": "2026-03-12T08:15:00Z",
      "city": "Louisville",
      "region": "KY",
      "postalCode": "40213",
      "country": "US"
    },
    {
      "carrierDescription": "Arrived at Facility",
      "shipmentStatus": "In Transit",
      "eventDate": "2026-03-11T22:45:00Z",
      "city": "Memphis",
      "region": "TN",
      "postalCode": "38118",
      "country": "US"
    }
  ]
}

Look up a single shipment by carrier tracking ID

If you have the carrier's tracking number but not the Shipium tracking ID:

Required path elements: carrierId and carrierTrackingId — The carrier identifier and carrier-assigned tracking number. See Supported Carriers for valid carrierId values.

Example cURL call:

curl -s "https://api.shipium.com/api/v1/tracking/carrier/ups/1Z9F0901YW17975733?excludeEvents=false" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Bulk search

For tracking multiple shipments at once (up to 100 per request):

Example cURL call — by Shipium tracking IDs:

curl -s -X POST https://api.shipium.com/api/v1/tracking/bulkTrackingSearch \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "shipiumTrackingIds": [
      "7a41e741-4cc2-48d6-a3a2-5dc565a378de",
      "b2345678-90ab-cdef-1234-567890abcdef"
    ],
    "excludeEvents": false
  }'

Example cURL call — by carrier tracking IDs:

curl -s -X POST https://api.shipium.com/api/v1/tracking/bulkCarrierTrackingSearch \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "trackingSearchRequests": [
      { "carrierId": "ups", "carrierTrackingId": "1Z9F0901YW17975733" },
      { "carrierId": "fedex", "carrierTrackingId": "277610036222" }
    ],
    "excludeEvents": false
  }'

Both bulk endpoints return a list of tracking results for each matched shipment. See Shipment Tracking API for all endpoints and parameters.

Track non-Shipium shipments

For shipments that were not created through Shipium's Carrier and Method Selection (e.g., shipments labeled through another system), you must register them before Shipium can track them. Shipment Tracking Registration API provides full details.

Register a single shipment

Example cURL call:

curl -s -X POST https://api.shipium.com/api/v1/tracking/register \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "carrierId": "ups",
    "carrierTrackingId": "1Z9F0901YW17975733",
    "carrierServiceMethodId": "ups-ground-service-method",
    "partnerShipmentId": "ORDER-12345"
  }'

Required fields:

• carrierId — The carrier identifier (e.g., ups, fedex). See Supported Carriers for valid values.
• carrierTrackingId — The carrier's tracking number. Must be 6–50 characters, alphanumeric with underscores, dashes, periods, and slashes.

Optional fields:

• carrierServiceMethodId — The carrier's service method
• partnerShipmentId — Your internal shipment/order ID (retained for 100 days)
• tenantId — Tenant identifier if using multi-tenant configuration
• shipDateTime — When the shipment was shipped
• fromCountryCode, fromPostalCode — Origin address details (improves tracking accuracy)
• toCountryCode, toPostalCode — Destination address details (improves tracking accuracy)

Example JSON response:

{
  "carrierId": "ups",
  "carrierTrackingId": "1Z9F0901YW17975733",
  "shipiumTrackingId": "7a41e741-4cc2-48d6-a3a2-5dc565a378de"
}

Save the shipiumTrackingId — you'll use it for subsequent tracking lookups.

Register multiple shipments in bulk

Register up to 100 shipments in a single request.

Example cURL call:

curl -s -X POST https://api.shipium.com/api/v1/tracking/bulkRegister \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "registrationRequests": [
      {
        "carrierId": "ups",
        "carrierTrackingId": "1Z9F0901YW17975733",
        "partnerShipmentId": "ORDER-12345"
      },
      {
        "carrierId": "fedex",
        "carrierTrackingId": "277610036222",
        "partnerShipmentId": "ORDER-12346"
      }
    ]
  }'

The bulk endpoint supports partial success — valid registrations succeed even if others in the batch fail. The response separates results into trackingRegistrations (successes) and failures (with detailed error information per failed item).

See Shipment Tracking Registration API for complete documentation including partial success handling and all field descriptions.

Re-registration behavior

Shipium-created shipments are automatically registered. If you attempt to register a shipment that was already created through Shipium within the last 60 days, the API returns the existing shipiumTrackingId rather than creating a duplicate. Shipments older than 60 days are treated as new registrations.

Receive updates via webhooks

Instead of polling the tracking API for updates, you can register a webhook to receive automatic notifications when tracking data changes.

Set up a webhook

1. Log in to the Shipium Console.
2. Navigate to Tracking > Tracking Webhooks.
3. Click Add Webhook and configure:
   • Endpoint URL. The HTTPS URL where Shipium will send tracking updates
   • Event types. Select which tracking events trigger notifications (e.g., tracking_updated).
   • Custom headers. Optionally add authentication headers that Shipium will include in every request.
4. Click Save to activate the webhook.

Shipium will send an HTTP POST request to your endpoint whenever a matching event occurs. Your endpoint must respond with a 2xx status code to acknowledge receipt. If delivery fails, Shipium retries automatically.

For complete webhook setup, payload format, debugging tips, and retry policies, see Webhooks for Tracking.

Track in the Shipium Console

The Shipium Console provides a web-based tracking interface:

1. Log in and navigate to Tracking > Track Shipment.
2. Enter one or more tracking IDs (Shipium tracking ID, carrier tracking ID, or partner shipment ID).
3. View the shipment timeline, current status, carrier details, and full event history.

The Console supports bulk search (up to 100 IDs), a visual event timeline, and CSV export for offline analysis. It's particularly useful for customer service investigations and ad hoc tracking lookups.

What's next