Tracking and updates
There are two main ways to track your shipments: pull-based tracking using the /track endpoint, and push-based updates using webhooks. This section discusses pull-based tracking. For more information about using webhooks, see the webhooks section.
Pull-based tracking involves periodically sending requests to the /orders/{tracking_number}/tracking endpoint to fetch the latest status of an order. This allows you to get updates whenever you need them.
To poll for updates:
- Determine the correct tracking URL. This is usually
https://track.shippit.com/{tracking_number}, where the tracking number is the Shippit tracking number of the order you want to track. - Send a GET request to the tracking URL, including your authentication headers.
- Shippit returns a JSON response containing the current status of the order, along with a history of tracking events, which you can parse in your own application.
You can choose the frequency of your polling based on your needs. For example, you might poll every few hours for standard orders or more frequently for express or priority orders.
Status code mapping
Shippit uses specific status codes to represent the different stages of an order’s journey. These statuses might not directly match the terminology used in your system. You might need to map these statuses to your own equivalents.
| API attribute | Web UI terminology | Web UI page | Definition |
|---|---|---|---|
processing | Processing | Any | The order is being moved from one tab to the next; this status can be an indicator that the order is stuck in between the two tabs |
order_placed | Order Placed | New Orders | The order is created in the Shippit New Orders tab; packaging size and courier assignment is yet to be confirmed |
despatch_in_progress | Packing Order | Ready to Ship | The order is in the Shippit Ready to Ship tab; packaging size and courier assignment is already confirmed |
ready_for_pickup | Booked for Delivery | Track | The order is on the Shippit Track tab; order details are sent to the selected courier for pickup and the merchant is already charged for booking |
pickup_failed | Pickup Failed | Track | The order status for futile pickup or no-goods-to-go (NGTG); this means the courier driver went to pick up the package from the merchant but it is not ready yet |
invalidated | - | - | Only for priority/same-day delivery orders; an order that was booked but cannot be picked-up because of driver unavailability |
cancelled | Cancelled | Track | An order that was previously booked but has not been picked-up was cancelled from the Track tab |
in_transit | Track | - | The order is already collected by the courier driver from the merchant; this can mean (a) the order is on its way to the depot or (b) is currently traveling in between depots |
untrackable | Untrackable | Track | The order was placed only to generate a plain label so no tracking events can be recorded; applicable for click-and-collect orders |
with_customs | - | - | Only for international orders; an order that has arrived at the destination country but is yet to be cleared by customs |
customs_awaiting_paym | - | - | Only for international orders; an order that has arrived at the destination country but requires duties and taxes to be paid by recipient |
customs_failed | - | - | Only for international orders; an order that has arrived at the destination country but was not cleared by customs |
customs_on_hold | - | - | Only for international orders; an order that has arrived at the destination country but is undergoing review by customs for any sort of reason not stated to Shippit by courier |
with_driver | Track | - | The order is onboard for delivery to the customer; this means it’s delivery day and the item is already on the courier driver’s van |
delivery_attempted | Delivery Attempted | Track | The courier driver attempted to deliver to the recipient address but no one is present to receive the order; a card is left at the delivery address so the recipient can arrange a redelivery |
delivery_failed | - | Track | The courier driver attempted to deliver to the recipient address but the recipient no longer resides/works in the destination |
insufficient_address | Insufficient Address | Track | The courier driver cannot locate the destination based on the indicated order delivery address; this could mean the address is incorrect or insufficient; the merchant can validate the address in Google Maps and supply the correct/complete address |
awaiting_collection | Awaiting Collection | Track | The courier driver delivered the item to a collection point for the customer to collect; this means that redelivery can no longer be arranged |
await_collection | - | - | Same as above; used by legacy integrations |
completed | Track | - | The package is successfully delivered |
partially_completed | - | Track | A component of a multi-parcel order is delivered but other parcels within the same order are not yet delivered |
parcel_completed | - | Track | Delivery of a multi-parcel order is completed |
lost | Lost | Track | The package is lost; if the order is covered by Shippit Transit Cover, a claim may be submitted |
damaged | Damaged | Track | The package is damaged; if the order is covered by Shippit Transit Cover, a claim may be submitted |
returned_to_sender | Returned to Sender | Track | The package was returned back to the merchant; this is possibly due to customer refusal to accept, customer failure to pick up from the designated collection point, redelivery attempts exceeded, incorrect address, or damaged package |
return_requested | Track | - | The merchant booked a return of the order from the customer; this means the return label is now created |
awaiting_drop_off | - | - | Only for users of the Shippit Returns portal; a customer chooses to drop off at the courier office instead of booking the delivery for pick-up from his/her address |
return_booked | - | - | Only for users of the Shippit Returns portal; a customer books the delivery for pick-up from his/her address instead of choosing to drop off at the courier office |
return_booking_failed | - | - | Only for users of the Shippit Returns portal; a customer who booked the delivery for pick-up from his/her address but is unable to ship out the item |
Triggers for order status updates
There are a range of triggers from both the Shippit UI, and the API that can move an order from one status to another. Generally, we do not recommend that you mix the UI and API workflows, but in some rare cases it is necesary. In that case, this table explains the triggers between the UI and API:
| Web UI action | API call | State on completion | Web UI tab |
|---|---|---|---|
| Add order | POST order | New Order | New Orders tab |
| Modify order | Delete order or Add order | New Order | New Orders tab |
| Confirm order | GET label | Ready to Ship | Ready to Ship tab |
| Cancel label | DELETE order label | Order Placed | New Orders tab |
| Book order | POST book | Booked | Track tab |
| Cancel order | DELETE order | Cancelled | not visible |
You can’t modify an existing order through the API. If you need to modify an existing order, use a deleter order call to delete the existing version of the order, then make a new add order call to load the order again in Shippit with the changed details.
The Cancel label UI action moves an order from the Ready to Ship tab back to the previous New Orders tab. This is different from the Cancel order UI action that can be done for any orders that have Booked for Delivery or ready_for_pick-up status. If an order has been picked up by a carrier, it can’t be cancelled using either the API or the UI. To cancel orders that have already been picked up, contact Shippit support.