# Get started

The Shipment Tracking Registration API enables you to receive tracking event data for shipments not created through Shipium's [Carrier and Method Selection](https://docs.shipium.com/docs/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. For a step-by-step guide to registering non-Shipium shipments and making your first API call, see [Getting Started with Tracking](https://docs.shipium.com/docs/getting-started-with-tracking). For a complete overview of Shipium's Track and Trace service, see [Track and Trace](https://docs.shipium.com/docs/track-and-trace).

### 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](https://docs.shipium.com/docs/supported-carriers);
- 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`);
- a tenant ID value (`tenantId`) if you are using tenants as part of your Shipium account;
- origin address details (`fromCountryCode`, `fromPostalCode`) to improve tracking accuracy;
- destination address details (`toCountryCode`, `toPostalCode`) to improve tracking accuracy;
- the date and time the shipment was shipped (`shipDateTime`).

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](https://docs.shipium.com/docs/shipment-tracking-api).

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

```curl
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.

```json
{
    "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
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.

```json
{
    "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](https://docs.shipium.com/docs/fulfillment-contexts#tenant-details) as part of your Shipium account.

```curl
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.

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

# Register multiple shipments in bulk for tracking

The bulk registration endpoint supports partial success. Valid registrations will succeed even if others in the batch fail. The request is limited to 100 tracking IDs at a time.

## Bulk tracking registration request example

```curl
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

```json
{
    "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 response example below.

```curl
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](https://docs.shipium.com/docs/supported-carriers) documentation.

```json
{
    "trackingRegistrations": [
        {
            "carrierId": "fedex",
            "carrierTrackingId": "1Z9F0901YW17975733",
            "shipiumTrackingId": "8deb2032-0110-4372-8543-72ec5000b4fd"
        }
    ],
    "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:

- [Terms and Definitions](https://docs.shipium.com/docs/common-terms)
- [Troubleshooting Guide](https://docs.shipium.com/docs/troubleshooting-guide)
- [Contact Shipium Support](https://docs.shipium.com/docs/contacting-shipium-support)

Updated 27 days ago

### What’s Next  
- [Track Non-Shipium Shipments](https://docs.shipium.com/docs/track-non-shipium-shipments)  
- [Track and Trace](https://docs.shipium.com/docs/track-and-trace)