Placing orders

The Shippit API is designed to handle a variety of order types, each with its own set of requirements and considerations. Understanding these order types is crucial to create a successful integration.

There are several shipping service levels that carriers can provide for orders. While different carriers might use different terms for these levels, Shippit organises them into these categories, based on the delivery speed and service level:

• Standard: regular shipments with an estimated delivery time of 3-5 business days
• Express: faster shipments, typically delivered the next day after the order is placed
• Priority: same-day deliveries, often used for urgent or time-sensitive shipments
• Click and collect: orders that customers pick up from a designated location, such as a retail store
• On-demand: similar to priority orders, but with a focus on immediate fulfilment, usually within a few hours.

Each order type has specific requirements in the API request payload, which is covered in the next section.

International orders

International orders have additional requirements compared to domestic orders, including:

• Customs information: details like tariff codes, country of origin, and customs declaration information
• Duties and taxes: depending on the destination country and the value of the goods, you might need to include information about duties and taxes
• Recipient identification: some countries require the recipient’s identification number for customs clearance, such as a passport or national ID number

For more information about what is required for international shipping, see the International shipping article on the Shippit Help Centre.

Cash on delivery

COD services are available for merchants with store addresses in Singapore and Malaysia, for these carriers:

• Aramex Singapore and Malaysia
• DHL
• Ninja Van

To mark an order as being COD, pass these parameters to the Order endpoint:

• cash_on_delivery_amount: used by the carrier to indicate the amount they need to collect on delivery
• courier_allocation: specifies which carrier is handling the order. This must be a carrier that supports COD. You can skip this field if you include courier_type.
• courier_type: specifies the preferred shipping service class for an order. The available options are standard or express. You can skip this field if you include courier_allocation.

Note that when you book a COD order, authority to leave (ATL) requests are ignored. Someone must be present at the delivery address to pay for the delivery.

For more information on COD orders, see the Understanding cash on delivery article on the Shippit Help Centre.

Request structure

The core of the Shippit order placement functionality is the /orders endpoint. To create an order, send a POST request to this endpoint with a JSON payload containing the order details.

The /orders payload is a nested JSON object with these main sections:

The top level object is order, which contains this order information:

• delivery_address: The recipient’s address (required).
• items: An array of items in the order (optional, but recommended for better tracking and reporting).
• parcels: An array of parcel specifications (required).
• user_attributes: Information about the customer (required).
• courier_type or courier_allocation: Specifies the service level or the specific courier (one of these is required).
• Various other optional fields, depending on the order type and courier.

Split orders

You can create orders that contain multiple shipments, with each shipment sent out using different carriers, or from different store or warehouse locations. The main benefit of grouping shipments within a single split order is to streamline communication to package receivers.

Split orders can have up to ten individual orders associated with it, as long as they all have the same recipient address. You can assign each order to a different carrier, using different service levels. You can create orders from different stores that are all associated with a single split order, but the stores must belong to the same company within your Shippit account.

For more information about creating split orders, see the Split orders section.

Service levels

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.

Return lifecycle

Unlike outbound orders, return orders do not move to the Ready to Ship page. They move directly to the Track page and change their status to Awaiting drop off, for items that need to be dropped off to an Australia Post outlet, or they change to Return requested, for carrier pickups.

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

For carrier pickups, a courier attends the recipient’s address and collects the product. The recipient must initiate the return by opening the tracking page and clicking to schedule the pickup. We do not currently provide the ability for a recipient to choose a date or time slot for the pickup, as this is not offered by the carriers.

For dropping off to Australia Post, the recipient must return the product to an Australia Post location.

For more information about creating return orders, see the Returns section.

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.

Tracking orders

In most cases, Shippit books the chosen carrier using the provided information, and supplies tracking information and notifications for the merchant and recipient as the order moves through the network.

However, you can also book and allocate a carrier for consignments outside of the Shippit platform. If you do this, you can still use Shippit to provide tracking information and notifications for the order. This is referred to as a tracking order, and applies if you’re only using Shippit for the tracking and notifications, and not for carrier booking.

You can create a tracking order in the same way as any other, but include the tracking_only attribute. Tracking orders also do not require the additional attributes that Shippit uses to match the the carrier’s internal information to Shippit.

Tracking order attributes:

• tracking_only: set to true to make the order a tracking order
• courier_allocation: the name of the courier in charge of the item (required)
• courier_job_id: the ID assigned by some carriers to the consignment
• parcel_attributes -> label_number: the label assigned by the carrier system to a parcel, used by Shippit to match the parcel number against the carrier’s parcel number (required)
• tracking_histories: optional status events that are added to the tracking page for the benefit of the recipient

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 their order. These items have just two fields, a status field and a timestamp in UTC format. These fields are used to indicate events such order_placement and ready_for_pickup.

The status field informs the user of the order state at that point in time and can be either order_placed or ready_for_pickup. The timestamp indicates when the status change happened.

These tracking history entries are recommended:

• 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 generates an initial tracking history for the order, set to ready_for_pickup at the point when Shippit received the API request.

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.

On demand orders

The on demand service level is offered by a range of carriers and services. On-demand carriers offer local delivery services with various delivery options, including delivery within two hours, same day delivery, or next day delivery. Additionally, some carriers provide a service where one driver picks up all orders at a fixed time.

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 the wallet_order_tracking: true is attached to the order creation request, the response includes an additional object wallet_order_tracking_attributes, containing 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
    }
  }
}

Shipping pallets

Australian occupational health and safety regulations stipulate that anything over 30kg must be lifted with machine assistance, such as a forklift. To stay within these regulations, drivers need to have anything over 30kg put on a pallet or a skid so that they can safely lift the goods on top their vehicle.

If you ship pallets, when you retrieve a quote with the quote endpoint, or create an order with the order endpoint, set the package_type attribute in parcel_attributes to pallet. This registers each of the parcels within the order as a pallet.

You can’t mix different package types within orders. If your order contains pallets, it must contain only pallets, and not have a mix of pallets and packages.

Orders with a package_type set to pallet are sent to a range of carriers that are able to support pallet shipments.

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.