About Shipium's tracking API

For organizations who would like to use the Shipment Tracking API for shipments that were not generated via Carrier and Method Selection, Shipium provides methods for either registering single shipments or registering multiple shipments in bulk.

You'll use the Shipment Tracking Registration API to register tracking events for non-Shipium initiated shipments, whether for single or bulk events. To track your events, please refer to the Shipment Tracking API.

To call the shipment registration API successfully, you must have the following for each shipment:

• a valid carrier ID value (carrierId) from Supported Carriers; and
• a valid carrier tracking ID value (carrierTrackingId). Acceptable characters are A to Z, a to z, 0 to 9, underscore, dash, period, slash, backslash, and no spaces. The value length must be between 6 (minimum) and 50 (maximum) characters, or the value will be rejected.

Optional field values you may choose to provide include:

• a shipment ID that is used within your organization (partnerShipmentId); and
• a tenant ID value (tenantId) if you are using tenants as part of your Shipium account.

📘

Re-Registering Shipium Shipments

Trackings created by Shipium are automatically registered. Attempting to register one again within 60 days of shipment generation will return a Shipium Tracking ID (shipiumTrackingId) you can use to search for it. Shipments older than 60 days will be considered new trackings.

You can register non-Shipium shipments as single or bulk tracking events.

🚧

Bulk Tracking Registration Limitation

All elements of the registration's requests must be valid, and bulk registration is limited to registering 100 tracking IDs at a time.

This guide provides support for registering single and bulk tracking events via several use cases. For shipments that use multiple carriers, Shipium retrieves all tracking events as if they were associated with the initial carrier regardless of multiple tracking IDs across carriers.

Use cases for calling the API

Single tracking registration

You can pass a partner shipment ID, omit a partner shipment ID, or pass a tenant ID for single tracking registration for non-Shipium shipments.

Tracking request example with a partner shipment ID

You can pass your organization's shipment ID (partnerShipmentId) in the request to be searched for later using the Shipium Tracking API.

The following sample client Uniform Resource Locator (cURL) request demonstrates inclusion of the partner shipment ID.

curl --location --request POST 'https://api.shipium.com/api/v1/tracking/register' \
--header 'Content-Type: application/json' \
--header $AUTHSTRING    \
--data-raw '{
    "carrierId": "ups",
    "carrierTrackingId": "1Z9F0901YW17975733",
    "carrierServiceMethodId": "ups-ground-service-method",
    "partnerShipmentId": "example-shipment-id"
}'

Tracking response example with a partner shipment ID

The following sample JavaScript Object Notation (JSON) response demonstrates inclusion of the partner shipment ID.

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

Tracking request example without a partner shipment ID

The following sample cURL request demonstrates omission of the partner shipment ID.

curl --location --request POST 'https://api.shipium.com/api/v1/tracking/register' \
--header 'Content-Type: application/json' \
--header $AUTHSTRING    \
--data-raw '{
    "carrierId": "ups",
    "carrierTrackingId": "1Z9F0901YW17975733",
    "carrierServiceMethodId": "ups-ground-service-method"
}'

Tracking response example without a partner shipment ID

The following sample JSON response demonstrates omission of the partner shipment ID.

{
    "carrierId": "ups",
    "carrierTrackingId": "1Z9F0901YW17975733",
    "shipiumTrackingId": "230de73d-79b7-436c-8bb7-31623c7cad73"
}

Tracking request example including a tenant ID

The following sample cURL request demonstrates inclusion of the tenant ID. The tenant ID must be valid within your network setup, if you are using tenants as part of your Shipium account.

curl --location --request POST 'https://api.shipium.com/api/v1/tracking/register' \
--header 'Content-Type: application/json' \
--header $AUTHSTRING    \
--data-raw '{
    "carrierId": "ups",
    "carrierTrackingId": "1Z9F0901YW17975733",
    "carrierServiceMethodId": "ups_ground_service_method",
    "tenantId": "tenant_id"
}'

Tracking response example including a tenant ID

The following sample JSON response demonstrates inclusion of the tenant ID.

{
    "carrierId": "ups",
    "carrierTrackingId": "1Z9F0901YW17975733",
    "shipiumTrackingId": "230de73d-79b7-436c-8bb7-31623c7cad73"
}

Bulk tracking registration

🚧

Bulk Tracking Registration Limitation

All elements of the registration's requests must be valid, and it's limited to registering 100 tracking IDs at a time.

The following cURL request and JSON response contain the carrier ID and carrier tracking ID with their corresponding Shipium tracking ID.

Bulk tracking registration request example

curl --location --request POST 'https://api.shipium.com/api/v1/tracking/bulkRegister' \
--header 'Content-Type: application/json' \
--header $AUTHSTRING    \
--data-raw '{
    "registrationRequests": [
        {
            "carrierId": "ups",
            "carrierTrackingId": "1Z9F0901YW17975733",
            "carrierServiceMethodId": "ups_ground_service_method",
            "partnerShipmentId": "partner_shipment_id"
        },
        {
            "carrierId": "ups",
            "carrierTrackingId": "1Z9F0901YW17975732",
            "carrierServiceMethodId": "ups_ground_service_method",
        },
         {
            "carrierId": "fedex",
            "carrierTrackingId": "277610036222",
            "carrierServiceMethodId": "fedex_2day_service_method",
            "tenantId": "tenant_id"
        }
}'

Bulk tracking registration response example

{
    "trackingRegistrations": [
        {
            "carrierId": "ups",
            "carrierTrackingId": "1Z9F0901YW17975733",
            "shipiumTrackingId": "8deb2032-0110-4372-8543-72ec5000b4fd"
        },
        {
            "carrierId": "ups",
            "carrierTrackingId": "1Z9F0901YW17975732",
            "shipiumTrackingId": "e435293a-8e26-4fc0-bff8-8a60b703093d"
        },
        {
            "carrierId": "fedex",
            "carrierTrackingId": "239F0901YW17975732",
            "shipiumTrackingId": "051421c5-83c3-4c2d-bb89-e6072f0042f0"
        }
    ]
}