Package Tracking API Migration Guide (2023.0)

The Package Tracking update released in version 2023.0 brought some new functionality by introducing a new entity called "Trackers" as well as a few changes to the Shipment and Package statuses.

What's New

If you weren't already using one of the following endpoints before the update was deployed, there are no changes needed! Otherwise, please continue reading.

Statuses

• Orders (order.info/order.search)
  • No changes
• Shipments (shipment.info/shipment.search)
  • Renamed "Loaded" to "Shipped" (loaded -> shipped)
• Packages (package.search)
  • Renamed "Not On Manifest" to "Packed" (not_on_manifest -> packed)
  • Renamed "On Manifest" to "Manifested" (on_manifest -> manifested)
  • Renamed "On Truck" to "Shipped" (on_truck -> shipped)
  • Added new status "Delivered" (delivered)

The following diagram shows the relationship between the different states and timestamps (described below).

Timestamps

The following new timestamps were added - no existing fields were changed.

• order.info/order.search - Added shipped_at and delivered_at
• shipment.info/shipment.search - Added packed_at, shipped_at and delivered_at for shipments and shipped_at and delivered_at for packages.
• package.search - Added shipped_at and delivered_at

Webhook Topics

The following new webhook topics were added for your consideration. Many of these are effectively duplicates so choose the ones that best suit your specific needs.

• order:shipped (all non-canceled items picked up by carrier)
• order:delivered (all non-canceled items shipped and all non-voided shipments delivered)
• shipment:shipped (all packages picked up by carrier)
• shipment:delivered (all packages delivered)
• package:manifested (added to a manifest)
• package:shipped (picked up by carrier)
• package:delivered (delivered to destination)
• tracker:updated (all status updates)
• tracker:delivered (status changed to delivered)
• tracker:exception (status changed to return_to_sender,failure,cancelled,error)
• Added trackers object key to shipment:packed payload.

Compatibility

To make the transition to the new statuses easy, we have deloyed the update on your system with a "compatibility flag" which causes the old statsus codes to be used. This way, you can update your integrations on your own time as described below. We plan to remove this compatibility flag on June 1, 2024 but it is advised to go ahead and make your code compatible as soon as possible.

How to Update

As the updated values are all read-only, the best way to accomodate the new statuses is to write your code so that it recognizes both the old and new status codes as the same. For example, this code:

switch ($shipmentStatus) {
    case 'packed':
        // Do something with packed shipment
        break;
    case 'loaded':
        // Do something with loaded shipment
        break;
}

could be updated to this:

switch ($shipmentStatus) {
    case 'packed':
        // Do something with packed shipment
        break;
    case 'loaded':
    case 'shipped':
        // Do something with shipped/loaded shipment
        break;
}

In this way the code works for both the old API response and the new one and so no special actions are needed, nor is it required to coordinate the update.