Overview

For partners who would like to use the Shipium 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.

Use this 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 Shipium Tracking API.

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

• a valid carrier ID value (carrierId) from the list of canonical carrier ID values; 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.

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 it's limited to registering 100 tracking IDs at a time.

This guide provides support for registering single and bulk tracking events via several use cases.

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 scope as a Partner, 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"
        }
    ]
}