Trackers

Create Trackers

Trackers are automatically created for you you generate a shipment or delivery on the PackageX platform. In those cases, however, we encourage you to keep listing to the update for the shipment/delivery because they will have much more complete information, as the trackers generally strip out some details.

When tracking a third party shipment, you'll just need to provide the tracking number and ideally the provider ID, as this can help speed up the request. If you don't provide the provider ID, we'll try to determine the provider based on the tracking number.

# Testing Trackers

In the sandbox environment, you may want to test exceptions rather than the "happy path" when a delivery is successfully delivered.

We offer a few way to force those exceptions. The tracker will still go through it's typical progression, but end in your predetermined status.

To trigger the predefined status, you'll update the first seven characters after the PKGX prefix to the fixed amount. The second set of characters can be any random combination of numbers and letters. We recommend something like this:

        function generateRandomString(length) {
  const alphanumeric = "ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789";
  let result = "";
  for (let i = 0; i < length; i++) {
    const index = Math.floor(Math.random() * alphanumeric.length);
    result += alphanumeric.charAt(index);
  }
  return result;
}

const string = generateRandomString(7);

//Create tracking number for typical

      

# Create Tracker

Create a tracker by providing the tracking number and optionally the provider ID.

        const data = {
  tracking_number: "PKGX-ABCDEFG-1234567",
  provider_id: null,
  chained_status: "in_transit",
  auto_close_shipments_option: "on_all_updates",
  auto_close_shipments_status: "picked_up",
};

const res = await fetch(`https://api.packagex.io/v1/trackers`, {
  method: "POST",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(data),
}).then((res) => res.json());

const tracker = res.data;

      

Once the tracker has been created webhooks will be sent anytime the tracker is updated. In the testing environment, the tracker will update approximately once every two minutes.

# Update Tracker

While you cannot update trackers for which you are not the provider, you are able to add, update, and delete metadata on the resource

        const data = {
  metadata: {
    internal_id: "hello-world",
  },
};

const res = await fetch(`https://api.packagex.io/v1/trackers/track_czhgjrk5JaVvyATPDbyURp`, {
  method: "POST",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(data),
}).then((res) => res.json());

const tracker = res.data;

      

# Optional Parameters

When creating or updating a tracker, you can set the tracker type by defining the type in the body of the request and setting it to inbound or outbound

# Tracker Intercept Status Outstanding Shipments

chained_status TrackingStatusOutstanding

# options?.tracker?.chained_status

        enum TrackingStatusOutstanding {
  provider_at_pickup
  package_accepted
  out_for_delivery
  provider_at_dropoff
  scheduled
  driver_dispatched
  package_at_waypoint
  in_transit
  pickup_available
  recipient_at_pickup
  added_to_container
  removed_from_container
  added_to_vehicle
  removed_from_vehicle
  delivered_to_provider
}

      

auto_close_shipments_option TrackerCloseShipmentsOption

# options?.tracker?.auto_close_shipments_option

This option determines how to handle outstanding shipments: on_provider_updates: Outstanding shipments will be closed only when the provider sends a tracking update to the shipment. on_all_updates: Outstanding shipments will be closed on any tracking update to the shipment. off: Outstanding shipments will be ignored.

Default: on_provider_updates

        enum TrackerCloseShipmentsOption {
  on_provider_updates
  on_all_updates
  off
}

      

auto_close_shipments_status TrackerCloseShipmentsStatus

# options?.tracker?.auto_close_shipments_status

When on_all_updates or on_provider_updates is active, you can select the following completed non-exception statuses for outstanding shipments:

        enum TrackerCloseShipmentsStatus {
  delivered
  picked_up
}