Trackers

Create Trackers

Trackers serve two primary purposes in the PackageX platform: automatically tracking shipments generated within the platform and monitoring third-party shipments.

For tracking third-party shipments, you'll need to provide a tracking number. Including the provider ID is recommended as it optimizes tracking initiation. Without a provider ID, the system will attempt to identify the provider based on the tracking number pattern.

The sandbox environment automatically processes these test tracking numbers through realistic delivery progressions, complete with appropriate status updates and location changes, enabling comprehensive integration testing.

# Testing Trackers

The sandbox environment provides a structured way to simulate and test various delivery scenarios using predefined tracking number patterns. Each pattern triggers a specific sequence of status updates, allowing you to test your system's handling of both successful deliveries and exception cases.

To test different scenarios, create tracking numbers using this format:

PKGX-[STATUS_CODE]-[RANDOM_STRING]

        function generateTestTrackingNumber(statusCode) {
    const generateRandomString = (length) => {
        return Array.from(
            { length }, 
            () => "ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"[Math.floor(Math.random() * 36)]
        ).join('');
    };
    return `PKGX-${statusCode}-${generateRandomString(7)}`;
}

const string = generateRandomString(7);

//Create tracking number

      

# Create Tracker

Create a tracker by either providing a tracking number or an inference ID. The tracker can be configured with various options to control its behavior and status updates.

        const data = {
  tracking_number: "PKGX-ABCDEFG-1234567",
  provider_id: null,
  location_id: "loc_xxx",
  manifest_id: "mfst_xxx",
  type: "inbound",
  chained_status: "in_transit",
  auto_close_shipments_option: "on_all_updates",
  auto_close_shipments_status: "picked_up",
  metadata: { custom_field: "value" },
  recipient_contact_id: "ctct_xxx",
  service_level_id: "ground",
  estimated_delivery_at: "1738057605000",
  tags: ["express_priority", "dry_cleaning"],
};

// OR create tracker from inference

const data = {
  inference_id: "inf_sl_xxx",
  type: "inbound",
  metadata: { custom_field: "value" },
  options: {
    tracker: {
      use_existing_tracking_number: false,
      chained_status: "in_transit",
      auto_close_shipments_option: "on_all_updates",
      auto_close_shipments_status: "picked_up"
    },
    transform: {
      use_existing_tracking_number: false
    }
  },
  tracking_update: {
    location_id: "loc_xxx",
    layout_id: "lay_xxx",
    status: "in_transit",
    images: ["img_url1", "img_url2"]
  }
};

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;

      

The tracker can be created in two ways:

1. Using a tracking number: Provide the tracking number and optional configuration parameters
2. Using an inference ID: Use an existing inference to create a tracker with additional options

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.

Required fields: Either tracking_number or inference_id

Optional fields for tracking number-based creation:

• type - Tracker type
• tags - Array of string tags
• metadata - Custom JSON metadata
• manifest_id - Associated manifest identifier
• chained_status - Outstanding tracking status
• service_level_id - Service level Id
• recipient_contact_id - Recipient contact Id
• estimated_delivery_at - Estimated delivery timestamp
• auto_close_shipments_option - Option for automatically closing shipments
• auto_close_shipments_status - Status for auto-closing shipments

Optional fields for inference-based creation:

• type - Tracker type
• metadata - Custom JSON metadata
• options - Configuration options for the tracker and transformations
• tracking_update - Additional tracking update information

The API returns a tracker object in the response data field upon successful creation (status code: 201).

# Update Tracker

Update a tracker's metadata, destination information, chaining configuration, and other properties. The endpoint supports modifying location data, contact information, and shipment chaining. While you don't have permission to modify trackers created by other providers, all users can add, update, or delete metadata on the resource.

        const data = {
  // Metadata updates
  metadata: {
    internal_id: "hello-world",
    custom_field: "value"
  },
  
  // Location and address information
  location_id: "loc_xxx",
  destination_location_id: "loc_xxx",
  destination_layout_id: "lay_xxx",

  // Destination address can be provided in multiple formats:
  destination_address: "123 Main St, City, State 12345",  // As a string

  // OR
  destination_address: {
    address_line1: "123 Main St",
    address_line2: "Suite 100",
    city: "City",
    state: "State",
    postal_code: "12345",
    country: "US"
  },

  // OR
  destination_address_id: "addr_xxx",  // Reference existing address
  // OR
  destination_address: "loc_xxx",  // Reference location
  
  // Contact information
  destination_contact_id: "con_xxx",
  sender_contact_id: "con_xxx",
  
  // Tracker configuration
  type: "inbound",
  chained_status: "in_transit",
  auto_close_shipments_option: "on_all_updates",
  auto_close_shipments_status: "picked_up",
  
  // Shipment chaining
  current_shipment_id: "ship_xxx",
  chaining: {
    // Add shipments to chain
    add: [
      { id: "ship_xxx", index: 0 }, // Add at specific index
    ],
    // Remove shipments from chain
    remove: ["ship_zzz"]
  }
};

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;

      

The endpoint allows you to update various aspects of a tracker:

• Metadata - Add or update custom metadata fields
• Location Information - Update location, layout, and address details
• Contact Information - Set destination and sender contacts
• Tracker Configuration - Modify type, status, and auto-close options
• Shipment Chaining - Add or remove shipments from the tracker's chain

When updating chained shipments:

• Shipments being added must not already be in the tracker
• Shipments being removed must exist in the tracker
• The current shipment must either be already chained or being added
• You can specify an index when adding a single shipment to position it within the chain

The API returns the updated tracker object in the response data field. Any modifications to the tracker will trigger appropriate webhook events to notify your systems of the changes.

# 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