Shipment Tracking Registration API
Track non-Shipium shipments consistently with Shipium's Shipment Registration Tracking API.
Get started
The Shipment Tracking Registration API enables you to receive tracking event data for shipments not rate shopped using Shipium's Carrier and Method Selection service. 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. You can refer to the Track Non-Shipium Shipments documentation for more information.
If you're interested in tracking shipments created in the Shipium platform, the Track and Trace and Track Shipments documents provide details.
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.
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.
This document provides instructions for using the API to register single and bulk shipments.
Register single shipments for tracking
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 Shipment Tracking API.
The following sample 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 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"
}
Register multiple shipments in bulk for tracking
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"
}
]
}
Bulk tracking registration request with partial success example
This registration request contains errors, which are detailed in the partial success example response below.
curl --location --request POST 'https://api.shipium.com/api/v1/tracking/bulkRegister' \
--header 'Content-Type: application/json' \
--header $AUTHSTRING \
--data-raw '{
"registrationRequests": [
{
"carrierId": "fedex",
"carrierTrackingId": "1Z9F0901YW17975733"
},
{
"carrierId": "fedex",
"carrierTrackingId": null
},
{
"carrierId": "nonExistentCarrier",
"carrierTrackingId": "1Z9F0901YW17975734"
},
{
"carrierId": "fedex",
"carrierTrackingId": "1Z9F0901YW17975735",
"carrierServiceMethodId": "nonExistentCarrierServiceMethod"
}
]
}
Bulk tracking registration response with partial success example
If a shipment registration results in an error, the detail will be provided in the failures object in the response. The trackingRegistrationRequestsIndex identifies the number of the shipment in the request with the error. Valid carrier and service method IDs can be found in the Supported Carriers documentation.
{
"trackingRegistrations": [
{
"carrierId": "fedex",
"carrierTrackingId": "CARRIER_TRACKING_ID",
"shipiumTrackingId": "shipiumTrackingId"
}
],
"failures": [
{
"carrierId": "fedex",
"carrierTrackingId": null,
"trackingRegistrationRequestsIndex": 1,
"errors": [
{
"field": "carrierTrackingId",
"detail": "is null or blank but is required"
}
]
},
{
"carrierId": "nonExistentCarrier",
"carrierTrackingId": "1Z9F0901YW17975734",
"trackingRegistrationRequestsIndex": 2,
"errors": [
{
"field": "carrierId",
"detail": "Invalid carrierId provided in request: nonExistentCarrier. See our docs for valid carrierIds"
}
]
},
{
"carrierId": "fedex",
"carrierTrackingId": "1Z9F0901YW17975735",
"trackingRegistrationRequestsIndex": 3,
"errors": [
{
"field": "carrierServiceMethodId",
"detail": "For carrierId fedex, invalid carrierServiceMethodId was provided: nonExistentCarrierServiceMethod. See our docs for valid ids"
}
]
}
]
}
FAQ
Q: How long does Shipium retain the partnerShipmentId value?
A: 100 days
Resources
Your Shipium team member is available to help along the way. However, you might find these resources helpful:
Updated 9 days ago