Create an order

The Shippit API is designed to handle a variety of order types, each with its own set of requirements and considerations.

This section discusses the different order types, the request structure to use to create an order, and how to manage labelling.

Order validation

If the validate field is passed and set to true, 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, a suggested address is returned instead.

Manual or automatic carrier selection

You can allocate a carrier 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. 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, or click_and_collect.

Parcel and product attributes

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, you can use a parcel_attributes field to provide 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 also specify a product_attributes field. In this case, the parcel_attributes no longer contains product information such as qty. Instead, each item under product_attributes specifies the number, dimensions, and other information about the products, while items under parcel_attributes 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 is assigned a separate parcel according to its dimensions. If this turned off, Shippit combines multiple product or parcel specifications into one.

Authority to leave

You can enable authority to leave (ATL) by default on 500g satchels.

To turn the ATL setting on or off, you must have Satchel 500g (A5) enabled in your package allocation settings in the Shippit UI. For more information about adjusting your package allocation settings, see the package allocation article in the Shippit help centre.

Whether or not a package is granted an authority to leave depends how carriers are allocated, if the setting is manually changed, or if carriers deem that a parcel can’t be left safely. When you confirm quotes, double check that the ATL setting is accurate.

Shipping alcohol

Important: You need to have pre-approval to ship alcohol through the carrier network to ensure the correct configuration is completed to identify alcohol shipments.

When you create an order containing alcohol in your Shippit account, specify identity_on_delivery under the features parameter in the order body to electronically notify carriers that they need to verify the identity of the package receiver.

When you include the identity_on_delivery flag, any authority to leave (ATL) settings for the order are ignored.

If you are using an Australia Post Wine Service product code to ship wine within Victoria, and you include the identity_on_delivery flag in the Order API payload, the order is automatically sent to Australia Post with a service code 49. Service code 49 is used by Australia Post to instruct drivers to verify the identity of the recipient on delivery.

For more information about shipping alcohol on the Shippit platform, see the Shipping alcohol article on the Shippit Help Centre.

Apple Pay Wallet order tracking

To offer your customer tracking in Apple Wallet, you need to have Apple Wallet order tracking enabled on your account. To get Apple Wallet order tracking enabled, contact your Shippit account manager, or contact Shippit support.

When you have Apple Wallet order tracking enabled, you can use it by adding the wallet_order_tracking property to the POST /orders request. When you use the wallet_order_tracking: true parameter in your order creation request, the response includes an additional wallet_order_tracking_attributes object, that 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
    }
  }
}

Transit protection

If you’re worried about lost or damaged parcels, you can use Shippit’s Transit Protection for easy and affordable protection against loss or damage. To ship packages with transit protection, you need to turn on transit protection in your merchant settings in your Shippit account.

Important: Before you turn on transit protection in your account, check the packaging guidelines, and the transit protection terms and conditions.

When you turn on transit protection in your account, every package you send is covered, as long as it has a declared order value associated with it, and it’s under the maximum coverage amount. To declare the order value, set the price parameter in product_attributes. Packages shipped without the price parameter set aren’t covered by transit protection.

For more information about transit protection, including coverage, see the transit protection article in the Shippit Help Centre.

Retrieve manifests

When you have created orders, you can call the book document endpoint to retrieve a manifest for your orders.

To fetch a manifest, start by retrieving the manifest_id with the Book API endpoint. The response body from this API call contains the manifest ID, which you need to be able to fetch the manifest.

When you have the manifest ID, you can periodically poll the Book document API endpoint to check for a new manifest. If the manifest is ready, a link to the PDF document is returned. If the manifest is not ready, the endpoint returns 422, with the error Document is not ready.