Submits a request for Quotes from different couriers on Shippit.

At minimum, a Quote requires a delivery location and information on the parcels being delivered. However, different couriers and delivery methods can require additional fields to satisfy their requirements. There is a maximum of 1000 parcels per quote request.

Listing all quotes vs listing a single quote

By default, Shippit will return a quote from the fastest / cheapest courier. However, for the purposes of showing different options, such as in a courier selection page, you may want to have Shippit display all quotes. To do this, pass the return_all_quotes field as true.

Note that the quotes returned are filtered based on the requirements given by different couriers. Depending on the info submitted in the order and the carrier settings in the Shippit admin page, you may not see quotes from all configured carriers.

Submits an Order to be created on Shippit.

At minimum, an Order requires a delivery location, user details, and parcel details. Shippit will then generate the order, allocate the courier, and fill in the origin location based on the provided info and merchant configuration on Shippit.

Note that the required fields for an Order can vary depending on the type of order, the requested courier, whether it is local or international, etcetera.

There is a maximum of 1000 parcels per quote request.

---

Order Lifecycle

Standard and Express Lifecycle

Web UI action	API call	State on completion	Where seen in UI
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

Click and Collect Lifecycle

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

Unlike standard / express orders, click and collect orders do not proceed 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.

Priority and Ondemand Order Lifecycle

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

Unlike standard / express orders, priority and ondemand orders do not need the book call. They are automatically booked by Shippit on the delivery date.

Ondemand orders are automatically booked by Shippit for an ASAP pickup, respecting store pick-and-pack time. Priority and Ondemand orders will remain on the New Orders page until dismissed by clicking the Label button or the GET label API call is made.

Return Order Lifecycle

Web UI action	API call	State on completion	Where seen in UI
N/A	POST order	New Order	New Orders page
Confirm order	GET label	Awaiting drop off / Return requested	Track page
Cancel order	DELETE order	Cancelled	Not visible

Unlike outbound orders, return orders do not proceed to Ready to Ship page. They move directly to the Track page and change their status to Awaiting drop off, for AusPost drop offs or Return requested, for carrier pickups.

• Carrier pickup - A courier will attend the recipient’s address and collect the product
  • Note: Recipient must initiate the return by opening the new tracking page and pressing a button to schedule the pickup. Right now there is no ability for the recipient to choose a date or time slot for the pickup, as this is not offered by the carriers.
• AusPost drop off - Your recipient must return the product to an AusPost location

Order validation

If the validate field is passed and set to true, then the order is not saved unless Shippit can validate the destination suburb and postcode to be a valid combination. If a valid combination is not found, Shippit will return a suggested address.

Manual or Automatic Courier selection

You can allocate a courier to an order in one of two ways: you can manually specify the courier as part of the order, or you can allow Shippit to automatically allocate a courier for you.

To manually specify a courier, pass the courier_allocation field with the identifier of the courier (see below).

To have Shippit allocate the courier for you, pass the courier_type field to specify the type of couriers that Shippit can choose from to allocate for you. This is used to stand for a service level such as standard, express, priority, click_and_collect.

Specifying Parcels and Products

Shippit needs to know the specifications of the products you want shipped and what parcels to use in shipping them. There is a maximum of 1000 parcels per quote request.

In the simplest case, this can be specified by a parcel_attributes field, which contains a list of Parcel specifications. Each item specifies the number, dimensions, and other information about the products being shipped, and the associated parcel. In this case, each parcel contains one type of product.

For more complex shipping arrangements, you can additionally specify a product_attributes field, which contains a list of Product specifications. In this case, the parcel_attributes will no longer contain product information such as qty. Each item under product_attributes would specify the number, dimensions, and other information about the products; while each item under parcel_attributes would separately specify the dimensions of the parcels. By mixing parcel and product specifications, you can define arbitrary groupings of products into parcels.

The number of parcels is further determined by the Allocate each item in an order to a separate carton setting in the Shippit administration page. If this is enabled, then each item will be assigned a separate parcel according to its dimensions. If this is disabled, then Shippit may combine multiple product or parcel specifications into one.

Standard orders vs tracking orders

In a standard order, Shippit will book the courier given the provided information and provide tracking information and notifications for the merchant and recipient on the status of the order.

If you've already booked and allocated a courier to your consignment outside of Shippit, however, you can still use Shippit to provide tracking and notifications for the order. This is called a tracking order. In this case, you're only using Shippit for the tracking and notifications, and not for carrier booking.

Creating a tracking order is the same as creating a standard order, only that you have to provide additional attributes so that Shippit can match the the courier's internal info to shippit. Note the following attributes:

• tracking_only required -- true - this makes this order a tracking order.
• courier_allocation required -- the name of the courier in charge of the item.
• courier_job_id -- the ID assigned by some carriers to the shipment / consignment.
• parcel_attributes -> label_number required -- the label assigned by the carrier system to a parcel, used by Shippit to match the parcel number against the carrier's parcel number
• tracking_histories -- one or two optional status events that will be added to the tracking page for the benefit of the recipient.

Passing tracking histories

In a tracking order, you can choose to pass tracking histories for the benefit of the recipient. These are shown to the recipient in the tracking page to inform them of the status of when the order has been processed.

These items have just two fields, a status field and a timestamp in UTC format, to indicate to the recipient events such as order_placement and ready_for_pickup. The status informs the user of the Order's state at that point in time and can be either order_placed or ready_for_pickup. The timestamp indicates when that change happened. The following tracking history entries are recommended to be placed:

• order_placed - set to the time when you received the order on your system.
• ready_for_pickup - set to the time when you book the order on Shippit.

If no tracking_histories entries are passed, Shippit will generate an initial tracking history for the order, set to ready_for_pickup at the point when Shippit received the API request.

Authority to leave

• When using 500g satchels,

  • When specifying No, you must have Satchel 500g (A5) enabled in your settings (Settings > Pick & Pack > Automatic Package Sorting > Carrier Default Presets).
  • When specifying Yes, you must have Satchel 500g ATL (A5) enabled in your settings (Settings > Pick & Pack > Automatic Package Sorting > Carrier Default Presets).
  • If nothing is specified, we assume ATL = No

• Note that the final ATL value also depends on how couriers are allocated and if users manually override the ATL option in the UI. It is important when confirming quotes that the ATL is set as desired.

Ondemand orders

Our "On-Demand Service Level" contains a range of ondemand carriers and services. On-demand carriers offer local delivery services with various delivery options. These options include 2-hour delivery, same-day delivery, and next-day delivery. Additionally, some carriers provide a service where one driver picks up all orders at a fixed time.

Return orders

You can see an example request for a return order on the right hand side under: Request samples > Example > Return Order.

The following 5 params are essential and return must be true:

• pickup_postcode
• pickup_address
• pickup_suburb
• pickup_state
• return

This will create a new order in the background, with the pickup/recipient data as the origin and the default merchant address as the destination and also set the order to the state awaiting_drop_off or return_requested, depending on the carrier allocation. We can also get a label for this order via the default label API.

Receivers will receive an email with their return label. This email provides the customer instructions on how to return their package/s. It is automatically triggered by Shippit, once a return order is confirmed by the merchant.

Limitations

Despite the existing order API limitations, the only addition for return orders is the selection of the carrier. Only certain carriers allow return orders.

In most cases, the merchant chooses only AusPost drop off as a valid return option.

A Shippit admin can, on behalf of a merchant, turn on or off carriers who would instead pick up the parcel for returns.

As this functionality is using the default order API, we can also create return orders for parcels that were not shipped originally via Shippit. As long as we supply the necessary pickup data in the request.

Apple Pay Wallet Order Tracking (coming soon)

After Apple Pay Wallet Order Tracking is successfully activated on your account, it can be used by providing an additional value wallet_order_tracking to the POST /orders request.

If the property wallet_order_tracking: true is attached to the order creation request, the response will include an additional object wallet_order_tracking_attributes, which contains the necessary data for the Apple Pay integration:

{
  "response": {
    "id": number,
    "tracking_number": string,
    [...]
    "wallet_order_tracking_attributes": {
      "order_type_identifier": string,
      "order_identifier": string,
      "web_service_url": string,
      "authentication_token": string
    }
  }
}

---

Service Level Mappings

Standard	Express	Priority	Ondemand
AlliedExpressOvernight	CapitalTransport	AlliedExpressSameday	DoorDashOndemand
AramexAuNz	CouriersPleaseExpress	Bonds	GrabExpress
AramexExpress	DirectCouriers	DoorDash	LalamoveOndemand
AramexInternational	EparcelExpress	EparcelOndemand	PandagoOndemand
CityLink	EparcelInternationalExpress	QxpressSameday	UberOndemand
CouriersPlease	FedExInternationalPriority	YelloOndemand
DhlEcommerce	KerryExpress
DhlEcommerceAsia	NewZealandPostExpress
DhlExpress	NinjaVanExpress
DhlExpressInternational	PbtCourierExpress
DirectFreightExpress	SekoExpress
Eparcel	SingPostExpress
EparcelInternational	StarTrackPremium
Fastway	TntOvernightExpress
FedExInternationalEconomy	TollPriority
FlashExpress
FourPXStandard
Gdex
HunterExpress
Janio
JanioInternational
Jnt
KerryStandard
LyneConnect
LynePlus
Neway
NewZealandCouriers
NewZealandPost
NinjaVanStandard
PbtCourier
Pgeon
Pickupp
PosMalaysia
Qxpress
SekoStandard
SingPost
Skybox
SmartRoutingInternational
StarTrack
Teleport
TeleportInternational
Tnt
Toll

Cancels an Order in Shippit using the tracking number.

The API first checks if the Order can be cancelled, ie., if its current state allows it, then returns an immediate response. If the Order is successfully cancelled, the API will answer with the Order with its state updated as cancelled. If it cannot be cancelled, it will throw a 422 error.

Retrieves labelling information for an Order using the tracking number.

The labelling information for an Order can only be retrieved once the Order has been processed and allocated a courier, which may take some time after the Order has been placed. If the Order is yet to be processed, you will get a 422 Unprocessable response.