To book a Shipment with the API, you only need to do three things:
-
Get rates – To have a good estimate of how much your Shipment's cost will be, you just need to Quote a Shipment and check out the different rates the couriers offer to you. You will also be able to see the rates that our On-Demand and Next-Day couriers offer.
-
Book a Shipment – To create a Shipment you only need to select a courier_service along with the same details you used to Get Rates and a Shipment will be made for you.
-
Track – Once you've received the Shipment's details, you can track the status and progress of the Shipment by entering in the tracking_number.
There are also two types of Statuses:
- Shipment Status: This is a generalised status that lets you know if a shipment is pending, active, or closed. Since shipments are all about movement, pending is when your item hasn't moved, active means it's being moved around by the courier, and closed means it stopped moving and is somewhere out there.
- Courier Status: While couriers have multiple types of statuses, we've generalised most of them into the following statuses for you.
| Courier Status | Description |
|---|---|
| pending | The shipment is awaiting pickup. |
| picked_up | The courier has confirmed the shipments pickup and is now tracking it in their system. |
| in_transit | The shipment is in the courier's logistics network and is moving from hub to hub. |
| out_for_delivery | The shipment is in the hub nearest to the customer and the customer can expect delivery within the day or two. If the customer is unavailable, the shipment will be move to the failed_delivery status. |
| delivered | The shipment was successfully delivered. |
| failed_delivery | The courier made an attempt to deliver the item and wasn't successful. Couriers have different attempt retries and after the maximum attempts, they will start returning the shipment. |
| returning | The shipment is on its way back to the pickup address. |
| returned | The shipment has been returned to the original pickup address. |
| cancelled | The shipment was cancelled and is now void. You will need to rebook the shipment if you wish to ship it again. |
| lost | The courier lost your item and is now subject to the courier's claims policy. |
Returns
The returning and returned statuses happen when a courier fails to deliver to a customer and the courier decides to ship it back to the from_address.
This is not to be confused with a customer receiving the order and requesting for a return because they were unhappy with the order or is subject to a refund & return. We don't currently support returns shipments at the moment.