Skip to main content

Tracking Parcel Status Updates

This guide explains how the Shipping Channels API automatically tracks your parcels and provides status updates, as well as how you can configure the frequency of these checks.

Automatic Status Tracking​

When you create a tracking parcel via the API, the system automatically initiates a process to monitor its status with the respective shipping provider. This ensures you receive timely updates on your parcel's journey.

Status updates are fetched periodically and recorded as status_updates for each tracking parcel. You can retrieve the full history of status updates for a parcel using the Get Tracking Parcel API Reference.

Configuring Check Frequency​

When creating a tracking parcel, you can specify two optional parameters to control the frequency and number of status checks:

  • check_delay_hours: The number of hours to wait before performing the next status check. This allows you to set a minimum delay between checks. The default value is 6 hours.
  • max_checks: The maximum number of status checks to perform for a parcel. Once this limit is reached, the system will stop checking for updates. The default value is 20 checks.

These parameters are useful for managing API usage and ensuring that resources are not spent on parcels that no longer require frequent monitoring (e.g., after delivery).

Example of creating a tracking parcel with custom check frequency:

{
  "shipping_channel_id": "ch_123456",
  "tracking_number": "1234567890",
  "check_delay_hours": 12, // Check every 12 hours
  "max_checks": 10 // Perform a maximum of 10 checks
}

For more details on creating tracking parcels, refer to the Create Tracking Parcel API Reference.

Retrieving Status Updates​

To get the latest status and the complete history of status updates for a tracking parcel, use the Get Tracking Parcel API Reference endpoint. The response will include a status_updates array containing details of each recorded status change.

Webhook Notifications​

For real-time notifications about status changes, we highly recommend setting up webhook subscriptions. You can subscribe to the tracking_parcel.status_changed event to receive an instant notification whenever a parcel's status is updated. Learn more in the Webhooks Guide.