Order flow
This section covers how the Shippit APIs work together to create orders and send them to a carrier for shipping. Depending on what features you need to enable, you might need to use different API endpoints. This section aims to give an overview of the various endpoints, how they can work together, and how they interact with the Shippit web UI.
Before you start
Before you get started with the Shippit APIs, spend some time sketching out how you want your integration to look. Some things you need to consider are:
- How much of the fulfilment process do you want to have in your integration?
- Do you want to be able to order, label, and book in your integration?
- What initial features you need to include, and what could be delivered in a later version of your integration?
- How much experience does your team have working with these kinds of integrations? Have they worked with carrier integrations in the past?
- Does your business have a platform that can perform a dispatching fulfilment process?
The order API
The core of the Shippit APIs is the order API. Use the order API to register orders into your Shippit account. When you register an order, make sure you include as much detail in the payload as you can. This helps Shippit allocate the most appropriate carrier for each order.
Key things to declare in your order payload:
- Dangerous goods
- For international orders, tariff codes or product descriptions
- Package dimensions
- Picking slip details
- Location in the warehouse
- SKU
- Product description
- Authority to leave
- Courier service level required
When you send a call to the order API, it responds with a tracking_number, which usually starts with PP. The tracking number in the response is a reference number that you can use in your other API calls to further interact with the order.
You can use Shippit’s parcel allocation engine, even if you don’t know the parcel dimensions. Make sure you provide the item dimensions, volumetric weight, and whether or not to consolidate items.
You can modify any order that’s in the order_placed state. This means you can modify the order after creation and before labeling begins, and not while quoting is in progress. For more information, see the modifying orders section.
For examples of how to construct your calls to the order API, see the code examples section.
The quote API
In most cases, offering a flat shipping rate helps to reduce cart abandonment, and if you use this method there is no need to interact with the quote API. However, in some cases, you might need to surface a shipping quote to customers in the cart, such as:
- Shipping bulky goods
- Determining if your carriers are able to deliver to an address
- Providing delivery estimates to customers
- Providing a range of carrier or service level options to customers
For more information about quoting and rate calculation, see the quoting section.
Important: You can’t get quotes on dangerous goods using the quote API.
When you send a request to the quote API, you need to provide at least a delivery address, and the parcel dimensions. A successful quote response includes one or more quotes from various carriers, including the price and delivery estimate at different service levels.
The label API
Use the label API to return shipping labels for your parcels. The label printing stage is the last stage before sending the booking to a carrier.
You can use the label API to print:
- A6 PDF shipping labels
- A4 picking slips
- ZPL labels
- A4 dangerous goods documents
- A4 Commercial invoice documents
When your order has had a label printed, it’s ready for dispatch.
The label API is also used to confirm which carrier your order is booked with, and provides the consignment or article details required by the carrier.
For more information about labelling, see the labelling section.
The book API
The book API is the final step, when an order is sent to the carrier for pickup. In most cases, you send the book API once a day, collecting all the orders for a single carrier for pickup. However, if you have large volumes, you might choose to have a morning and an afternoon pickup from the carriers you use the most.
When you send a book API call, you include all orders that are ready for pickup. The response to the book API call is a manifest document, which most carriers require to be able to process your orders. You receive one manifest for each carrier service you have booked with, and you can push multiple orders from multiple carriers at multiple service levels with a single book API call.
Using the Shippit web app in conjunction with the APIs
You might want to use the Shippit web app in addition to your own custom integration. There are also some cases where you need to use the Shippit web app to finalise some details. Using a mixed approach can simplify your development process, or allow you to ship a leaner platform as a phase one for your project, while you build out other parts of the integration. Even if you do decide to use a mixed approach, you still need to ensure you are sending as much information as possible with the order API call.
For more information about using the Shippit web app, see the Shippit help centre.
Webhooks
You can use a Shippit webhook to provide tracking status updates for your customers, as their parcel makes its way through the carrier network. Tracking is initialised on an order when it has been booked with the carrier and starts its outbound journey.
For more information about the available webhooks, see the webhooks section.
Carrier allocation
The most important things that Shippit provides you as part of the Shippit APIs is the ability to allocate orders to the best suited carriers. Carrier allocation happens in two steps: validation, and allocation.
Validation occurs first, and is the process by which Shippit checks the information about your order, such as the to and from postcodes, origin and destination, type of goods, and package dimensions, and sends that information out to a range of carriers to find which ones are able to fulfil the request. The more information you provide for each individual order improves the quality of the carrier quotes that are received back.
Allocation is the second step, and occurs when Shippit uses your individual account settings to determine which carrier of those that respond is the most suited to accept the order. The more detail you have specified in your account settings helps Shippit to provide the best suited carrier for the job.
Shippit also provides many tools to help improve your pick and pack process. Always provide as much information as you can about the dimensions and weight of individual items, and the available packaging options.
Package allocation
Package allocation primarily uses weight for the calculation. When the carrier picks up your order, they calculate how much the charged weight is, which is the greater of the dead weight and volumetric weight. In most cases, you need to make sure that you are including the volumetric weight, so that Shippit can make an accurate package allocation.
The formula to calculate volumetric weight in kilograms is: > length (cm) x width (cm) x height (cm) / cubic ratio For example, if a box of pillows with 2kg dead weight has dimensions 70 x 40 x 40cm, and the cubic ratio is 4000, the volumetric weight of the parcel is 28kg. This means the charged weight is 28kg, which is the figure used by Shippit and the carrier for invoicing.
To make sure you are getting accurate parcel allocation, make sure you add custom parcel presets in your Shippit parcel allocation settings.
Order flow in both the API and UI
As orders are created, fulfilled, and shipped, they move through various stages. Each stage has an API call associated with it, which corresponds to an action taken on a particular screen in the Shippit user interface.
Standard and express lifecycle
| Web UI action | API call | State on completion | UI page |
|---|---|---|---|
| Add order | POST order | New Order | New Orders page |
| Confirm order | GET label | Ready to Ship | Ready to Ship page |
| Cancel order | DELETE order | Cancelled | Not visible |
| Book order | POST book | Booked | Track page |
For more information about creating orders with this service level, see the Service level section.
Click and collect lifecycle
Unlike standard and express orders, click and collect orders do not move to the Ready to Ship page. They remain in the New Orders page until you call either the Book API or click the Label button.
| Web UI action | API call | State on completion | Where seen in UI |
|---|---|---|---|
| N/A | POST order | Packing order | New Orders page |
| Label | GET label | Packing order | New Orders page |
| Cancel order | DELETE order | Cancelled | Not visible |
| Book order | POST book | Booked | Track page |
For more information about creating orders with this service level, see the Service level section.
Priority and on demand lifecycle
Unlike standard and express orders, priority and on demand orders do not need the book call. They are automatically booked by Shippit on the delivery date.
On demand orders are automatically booked by Shippit for an ASAP pickup, respecting store pick-and-pack time. Priority and on demand orders remain on the New Orders page until they are dismissed by clicking the Label button, or the GET label API call is made.
| Web UI action | API call | State on completion | Where seen in UI |
|---|---|---|---|
| N/A | POST order | Packing order | New Orders page |
| Label | GET label | Booked | Track page |
| Cancel order | DELETE order | Cancelled | Not visible |
For more information about creating orders with this service level, see the Service level section.