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,
};

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 minute.

# 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;