Trackers

Models

# Tracker Model

The tracker represents a single tracking number with one or more parcels that are being tracked.

object "tracker"
The description of the model.

created_at DateTime
Time in epoch seconds when this resource was created.

updated_at DateTime
Time in epoch seconds when this tracker was last updated.

updated_by string || null
The ID of the org or key who last updated the tracker.

estimated_delivery_at DateTime || null
Expected date and time of delivery for the tracker.

id string
Unique identifier for the tracker prefixed with track_.

tags Array<string>
A unique array of tags aggregated from all shipments in this tracker.

        enum ShipmentTags {
  fragile
  perishable
  dry_cleaning
  lithium
  alcohol
  cannabis
  confidential
  express_priority
  security_concern
  cold_storage
  high_value
  requires_equipment
}

      

organization_id string
Unique identifier for the organization that owns this tracker. This will always be your organization ID.

type TrackerType
Enum indicating the direction of the shipment:

        enum TrackerType {
  outbound // Packages being sent from your location to another destination
  inbound // Packages being received at your location from another sender
}

      

chained_status TrackingStatusOutstanding
Determines how the tracker's overall status should be calculated when multiple shipments are chained together. It's default value will be package_at_waypoint

        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
Controls when previous shipments in a chain should be automatically closed. It's default value will be on_provider_updates

        enum TrackerCloseShipmentsOption {
  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.
}

      

auto_close_shipments_status TrackerCloseShipmentsStatus
Specifies which status to apply when automatically closing previous shipments in a chain. When auto_close_shipments_option is enabled, previous shipments will be marked with this status.

        enum TrackerCloseShipmentsStatus {
  delivered
  picked_up
}

      

tracking_number string || null
Provider-specific string used to track the shipment.

tracking_url string
A publicly accessible URL where anyone can view the tracking information for this tracker. The URL is in the format https://{domain}/external/shipments/{tracking_number}.

tracking_updates TrackingUpdate[]
A list of waypoints this tracker has passed through, ordered from oldest to newest. See Tracking Update Model

metadata object
Custom key-value pairs that can be attached to the tracker. Keys must be strings and values can be strings, numbers, or booleans. This field is searchable and can be used to store additional information about the tracker.

Example:

        {
  "order_id": "123456",
  "customer_reference": "PO-789",
  "priority": "high",
  "is_fragile": true
}

      

shipments Shipment[]
An array of shipment objects associated with the tracker.

manifest_id string optional
The ID of the manifest associated with this tracker.

destination_address Address
The address where the shipment is to be delivered. This is typically the recipient's address for outbound trackers or your location's address for inbound trackers.

destination_layout Layout
The layout within the destination location where this shipment should be delivered. This is typically used for organizing deliveries within a location, such as specific floors, departments, or storage areas.

destination_location Location
The final delivery location for this tracker.

destination_contact Contact
The contact information for the individual who will receive the shipment at the destination. For outbound trackers, this is the recipient contact. For inbound trackers, this is typically a contact at your location.

sender_contact Contact
The contact information for the individual or entity sending the shipment.

final_chained_shipment_id string
The ID of the last shipment in a sequence of connected shipments, used to track the final leg of multi-stage deliveries.

current_shipment_id string
The ID of the shipment that is currently active or being processed within the tracker.

status TrackingStatus
Current status of the tracker indicating where the package is in its delivery journey. This status is updated as tracking updates are received and reflects the most recent state of the delivery.

        enum TrackingStatus {
  rates_generated        // Shipping rates have been generated but shipment not yet created
  created                // Tracker has been created but not yet picked up
  address_issue          // There is an issue with the delivery address
  provider_at_pickup     // Carrier is at pickup location
  contact_provider       // Customer needs to contact the carrier
  delayed                // Delivery is delayed
  attempted              // Delivery was attempted but not completed
  rescheduled            // Delivery has been rescheduled
  scheduled              // Delivery is scheduled
  driver_dispatched      // Driver has been dispatched for pickup/delivery
  out_for_delivery       // Package is out for delivery
  provider_at_dropoff    // Carrier is at delivery location
  package_accepted       // Package has been accepted by carrier
  package_at_waypoint    // Package is at an intermediate location
  in_transit             // Package is in transit
  pickup_available       // Package is available for pickup
  package_damaged        // Package has been damaged
  delivered              // Package has been delivered
  picked_up              // Package has been picked up
  return_to_sender       // Package is being returned to sender
  package_undeliverable  // Package cannot be delivered
  package_lost           // Package has been lost
  canceled               // Delivery has been canceled
  added_to_container     // Package added to a container
  removed_from_container // Package removed from a container
  added_to_vehicle       // Package added to a vehicle
  removed_from_vehicle   // Package removed from a vehicle
  recipient_at_pickup    // Recipient is at pickup location
  delivered_to_provider  // Package delivered to another carrier
}

      

_search object
A special property that will be included if searching through trackers. This is a flat object that contains various properties related to the search results. Each property may include <mark> tags around characters that have matched the search query, allowing for easy highlighting in the user interface. The properties within this object provide relevant information about the search results, such as recipient names, emails, contact groups, tracking numbers, relevance scores, and the original query used for the search.

Example:

        _search": {
  "recipient_names": ["<mark>kyle</mark> grzybowski"],
  "sender_names": ["carl's golfland"],
  "recipient_emails": ["<mark>kyle</mark>@packagex.xyz"],
  "sender_emails": ["carl.golfland@packagex.io"],
  "destination_contact_group": [],
  "sender_contact_group": [],
  "tracking_number": "PKGX-0K8BVS1-US5XTCW",
  "relevance_score": 1,
  "query": "kyle"
}