Order schemas

This section contains the schemas for the Order API.

Request body schema for order

Name	Type	Required	Description
parcel_attributes	Array, see table	true	An array of parcel specifications to be included in the order. There is a maximum of 1000 parcels per request. Each item can be used to specify the qty, dimensions, and other information about the products being shipped, and the parcel used to ship it. If the Allocate each item in an order to a separate carton setting is enabled in the Shippit administration page, then each item is assigned a separate parcel according to the dimensions given. Otherwise, Shippit may combine multiple items into a single parcel. If the product_attributes field is present, then product information is specified in entries there, separate from the parcel information. In which case each parcel entry represents a single parcel.
product_attributes	Array, see table	false	an array of product details. If this is present, each item in parcel_attributes represents a separate parcel, while each line in product_attributes represents a product line item. There is a maximum of 1000 parcels per request.
authority_to_leave	string	false	whether or not the order can be left unattended at the delivery address, options are Yes or No
cash_on_delivery_amount	number	false	Used by some carriers, such as NinjaVan, to indicate amount to be received on delivery for cash on delivery orders.
courier_type	string	false	The service level for the order. For a complete list of service level strings, see the Service levels section in the Developer Guide. If you want to specify the courier in the request, use courier_allocation instead. You must specify either courier_allocation or courier_type. If omitted or invalid, an enabled carrier that matches the default service level is allocated instead. The default service level is standard and can be configured by Shippit on request.
courier_allocation	string	false	You must specify either courier_allocation or courier_type. For a complete list of carrier reference strings, see the Carriers section in the Developer Guide. If omitted or invalid, an enabled carrier that matches the default service level is allocated instead. The default service level is standard, and can be configured by Shippit on request. If tracking_only is set to true, then courier_allocation is required.
receiver_contact_number	string	false	conditional – number of the person receiving the order, may be different than the user who purchased the order. Mandatory for International orders.
receiver_name	string	false	name of the person receiving the order if different than the user who purchased the order
retailer_invoice	string or number	false	Merchant invoice number - the customer-facing sales order reference of the order. This is what the recipient sees on the shipping label, packing slip, customs declaration, receipt, etc. This attribute accepts numeric values, but it’s recommended that you pass this in as a string where possible.
retailer_reference	string	false	Merchant reference id - if the merchant uses a separate internal reference id for the order, it can be placed here.
receiver_language_code	string	false	Two-letter ISO 639-1 language code of the recipient. Used to determine the language of tracking notifications and other communications. Defaults to EN
validate	boolean	false	when true, run validations against the submitted order and only save the order if the supplied parameters are valid. Validations run - destination suburb and postcode checked against a list of known postcodes / suburbs. - If a valid combination is not found, a suggested address is returned.
product_currency	string	false	Three letter ISO 4217 currency code that applies to the order, which is sent to the carrier and presented on the customs invoice. Defaults to AUD
suppress_communications	boolean	false	if true, all notifications are suppressed for this specific order
tracking_only	boolean	false	Whether the Order being passed is a tracking order or not. A tracking order is an order where the courier was allocated outside of Shippit, but was loaded into Shippit to take advantage of tracking and notifications. If this is present and set to true, this order is a tracking order. If it is set to true, courier_allocation must be present.
tracking_histories	Array, see table	false	An array of Tracking History statuses that are are shown to the recipient as part of the order’s history on the tracking page.
user_attributes	Array, see table	false	Represents the customer details attached to the order.
features	[string]	false	Some carriers provide add-on services or features that you can indicate in the order. These services are identified by a unique string, and are dependent on the carrier. To request these services, add the appropriate string in this field. For example, white_glove, or identity_on_delivery.
customer_shipping_fee_paid	string	false	Shipping fee paid by the customer. This is displayed on the commercial invoice for international orders to support accurate duties and tax calculation by customs. This fee is not related to the Shippit quote. When not provided, no shipping fee is displayed on the commercial invoice.
description	string	false	Goods description for the order. May appear in labels for international orders. If not provided, defaults to the goods type setting from the international shipping settings of the merchant account. Description is mandatory for international orders when validate is set to true.
duties	number	false	The duty amount for an order. This is displayed on the commercial invoice for international orders to calculate the invoice total. Duties are not returned by Shippit. When not provided, no duties amount is displayed on the commercial invoice. eg: 12.90
tax_amount	number	false	The tax amount for an order. This is displayed on the commercial invoice for international orders to calculate the invoice total. When not provided, no tax amount is displayed separately on the commercial invoice. eg: 2.39
customs_clearance_attributes	Array, see table	false	Represents customs clearance parameters for international orders.
pickup_postcode	string	false	Pickup postcode for the return order * required for return orders
pickup_address	string	false	Pickup address for the return order * required for return orders
pickup_suburb	string	false	Pickup suburb for the return order * required for return orders
pickup_state	string	false	Pickup state for the return order Australian states valid options are: NSW, QLD, ACT, WA, NT, SA, VIC, TAS * required for return orders
return	boolean	false	Whether the order being passed is a return order or not. This method of processing returns is no longer recommended. See returns for more information.
pickup_at	string	false	The start of the pickup window for OnDemand orders in the format YYYY-MM-DDTHH:mm:ss+HH:mm
pickup_deadline_at	string	false	The end of the pickup window for OnDemand orders in the format YYYY-MM-DDTHH:mm:ss+HH:mm
dropoff_at	string	false	The start of the drop off window for OnDemand orders in the format YYYY-MM-DDTHH:mm:ss+HH:mm
dropoff_deadline_at	string	false	The end of the drop off window for OnDemand orders in the format YYYY-MM-DDTHH:mm:ss+HH:mm
delivery_company	string	false	Company name for the delivery
delivery_address	string	true	Delivery address for the order
delivery_suburb	string	true	Delivery suburb for the order
delivery_state	string	true	Delivery state for the order. Australian States valid options are NSW, QLD, ACT, WA, NT, SA, VIC, TAS
delivery_postcode	string	true	Delivery postcode for the order
delivery_country_code	string	false	Two letter country code
delivery_timezone	string	false	Time zone for the delivery
delivery_instructions	string	false	Special delivery instructions for the order, limited to 55 characters
group_order	Array, see table	false	Represents the group order details that the order belongs to.

Request schema for parcel_attributes

Name	Type	Required	Description
title	string	false	conditional – Title or description of the product. Mandatory for international orders with specific couriers.
package_type	string	false	Set to pallet if the package is a pallet, otherwise leave this field out. You can’t mix pallets with other types of parcels within an order.
packed	integer	false	The number of products packed; used in partial orders, or otherwise when the number of products in the parcel is less than the total in the order. If not present, set to product quantity. If this is present, at least 1 item should have packed greater than 0. For international orders, all items should have packed greater than 0.
sku	string	false	conditional – Stock Keeping Unit (SKU) code of the product, for stock keeping purposes. Mandatory on international orders with specific couriers.
product_line_id	string	false	Product line associated with product. Like SKU, this is also for stock keeping purposes, and can be used when SKU would not be enough (e.g. an order containing multiple lines with the same SKU)
origin_country_code	string	false	Two-letter country code (ISO 3166-1 Alpha-2) for the product’s origin country. This is used in customs tracking for International shipments. Defaults to the home country of the Merchant.
location	string	false	Location of the product
dangerous_goods_code	string	false	This is the DG code required when making dangerous goods declarations. Before you can declare orders as having dangerous goods, you must first request for dangerous goods to enabled for your account. Contact Shippit Support or your account manager to have this enabled. DG surcharges are often charged on the weight of the order, so it is recommended to split your order into multiple orders if your order contains either: - both dangerous and non-dangerous goods, or - more than one dangerous goods code
dangerous_goods_text	string	false	Additional information related to dangerous goods being shipped
dangerous_goods_class	string	false	This is the DG class when making dangerous goods declarations.
price	number	false	Unit price of each product line item. Used in the packing slip and customs declarations.
weight	number	false	Weight of the parcel in kilos.
depth	number	false	Depth of the parcel in metres
length	number	false	Length of the parcel in metres
width	number	false	Width of the parcel in metres.
label_number	string	false	Parcel number in the carrier system. This is used when the order is a tracking order, to match the parcel number in a carrier against the parcel recorded in shippit.
qty	number	false	conditional – The number of products specified by the entry. There is a maximum of 1000 parcels per quote request. Should not be present if a product_attributes key is present in the request. If Allocate each item in an order to a separate carton is enabled in Shippit, a separate parcel is generated for each product listed.

Request schema for product_attributes

Name	Type	Required	Description
title	string	false	conditional – Title or description of the product. Mandatory for international orders with specific couriers.
packed	integer	false	The number of products packed; used in partial orders, or otherwise when the number of products in the parcel is less than the total in the order. If not present, set to product quantity. If this is present, at least 1 item should have packed greater than 0. For international orders, all items should have packed greater than 0.
sku	string	false	conditional – Stock Keeping Unit (SKU) code of the product, for stock keeping purposes. Mandatory on international orders with specific couriers.
product_line_id	string	false	Product line associated with product. Like SKU, this is also for stock keeping purposes, and can be used when SKU would not be enough (e.g. an order containing multiple lines with the same SKU)
origin_country_code	string	false	Two-letter country code (ISO 3166-1 Alpha-2) for the product’s origin country. This is used in customs tracking for International shipments. Defaults to the home country of the Merchant.
location	string	false	Location of the product
dangerous_goods_code	string	false	This is the DG code required when making dangerous goods declarations. Before you can declare orders as having dangerous goods, you must first request for dangerous goods to enabled for your account. Contact Shippit Support or your account manager to have this enabled. DG surcharges are often charged on the weight of the order, so it is recommended to split your order into multiple orders if your order contains either: - both dangerous and non-dangerous goods, or - more than one dangerous goods code
dangerous_goods_text	string	false	Additional information related to dangerous goods being shipped
dangerous_goods_class	string	false	This is the DG class when making dangerous goods declarations.
tariff_code	string	false	Tariff or HS code for international orders declarations
mid_code	string	false	Manufacturer identification code (MID) used for customs declarations. This code identifies the manufacturer of the product and is required for some international shipments, particularly to the United States.
quantity	integer	false	The number of products
price	number	false	Unit price of each product line item. Used in the packing slip and customs declarations. Required for transit protection.

Request schema for tracking_histories

Name	Type	Required	Description
status	string	true	The status of the order
timestamp	string	true	The date / time when the status change occurred.

Request schema for user_attributes

Name	Type	Required	Description
email	string	true	The customer’s email address. Must match regular expression as defined in https://html.spec.whatwg.org/multipage/input.html#valid-e-mail-address
first_name	string	true	The customer’s first name. If last_name is not provided, then it is used as the customer’s full name.
last_name	string	false	The customer’s last name
mobile	string	false	Mobile number of the user who purchased the order. This could be different to the person receiving the order.

Request schema for customs_clearance_attributes

Name	Type	Required	Description
tax_id_type	string	false	The Shippier’s tax id type which is passed to a carrier for the purpose of customs clearance. Valid values include: - EORI - IOSS - LVG - OSR - VOEC - VAT/GST - FTZ - DAN - TAN - DTF - EIN - SSN - DUN - FED - STA - CNP - GBVAT - NZ IRD
tax_id_country_code	string	false	The issuing country of the tax id number in in ISO 3166 Alpha-2 format. eg. GB for Great Britain
tax_id_number	string	false	The tax id number that is declared against this order.
incoterm	string	false	The incoterm to use for the order. For valid values, see International orders in the Developer guide.
export_reason	string	false	The reason for exporting these goods. For valid values, see International orders in the Developer guide.
recipient_id	string	false	A free text field to provide a identification number for a recipient. For example, a citizen identification number or passport number which is required for customs clearance for some international destinations. eg: PA1992991
receiver_freight_charge_amount	number	false	The amount charged to the receiver for freight services. This represents the cost that the receiver is responsible for paying as part of the freight or shipping charges.

Request schema for group_order

Name	Type	Required	Description
id	string	true	The group order ID. Retrieved from the response when creating the group order.

Response schema for order

Name	Type	Required	Description
tracking_number	string	true	Unique random ID assigned by Shippit to an order. This can be used as a reference for future API calls or support tickets.
slug	string	true	tracking_number in lowercase.
parcel_attributes	Array, see table	false	An array of parcel specifications that were created with the order.
products	Array, see table	false	An array of product items specified in the order. If product information was not provided, this array is blank.
tracking_url	string	false	The URL of the order’s customer tracking page.
return	boolean	false	Whether or not the order is a return order. This method of processing returns is no longer recommended. See returns for more information.
id	integer	false	Shippit internal numerical ID
processing_state	string	false	Internal order status set and progressed by Shippit upon creation.
invoice_number	any	false	Internal link between an order and a Shippit invoice - this is almost always null on order creation.
courier_delivery_instructions	string	false	Delivery instructions as sent to the courier. In most cases, this is the same as the delivery_instructions passed into the request. Some couriers, however, have a specific format expected when sending delivery instructions through their API. This contains the actual delivery instructions that get sent through the courier API when booked.
courier_name	string	false	Human-readable name of the courier that has been allocated to the order, or null if the order hasn’t been allocated yet. If you’re creating orders by passing in courier_type, the courier is usually not yet assigned at order creation and you receive null. Courier allocation is run as a background process depending on the merchant preferences, available couriers, and quotes returned by the couriers, which may take a few seconds to complete after order creation. If you’re passing in a specific courier keyword in courier_allocation, this reflects the courier that is specified. Note that the Shippit web user can also update the courier in between API calls. The final courier that has been assigned can be determined from the LABEL call.
price	any	false	The price that is charged for the allocated order. If you’re creating orders by passing in courier_type, the courier is usually not yet assigned at order creation and you receive 0. Courier allocation is run as a background process depending on the merchant preferences, available couriers, and quotes returned by the couriers, which may take a few seconds to complete after order creation. Note that the Shippit web user can also update the courier in between API calls. The final courier and quoted price can be determined from the LABEL call. If the quoted price is still 0 during the LABEL call, something likely went wrong with the courier selection and the order may need to be amended.
customs_documents_require_printing	boolean	false	Whether or not customs documents, such as declarations, invoices, etc for the Order that should be printed and included with the shipment. By default this is true for International orders.
courier_type	string	false	The courier allocated to the order. See the ORDER CREATE courier_allocation API for available keywords.
tracking_histories	Array, see table	false	An array of Tracking History statuses that are are shown to the recipient as part of the order’s history on the tracking page.
state	string	false	The state of the order as progressed by the merchant.
user	Array, see table	false	Represents the recipient of the order
documents	Array, see table	true	Documents attached to the label response

Response schema for parcel_attributes

Name	Type	Required	Description
qty	number	false	The number of parcels specified by the entry. Depending on how the merchant account is configured, the number of parcels generated may not match the number of parcel attributes passed in. By default, Shippit tries to combine all parcel attributes into a single parcel with the sum of the weights. However, if Allocate each item in an order to a separate carton is enabled, then Shippit generates one parcel entry for each parcel entry sent in.
weight	number	false	Weight of the parcel in kilograms.
depth	number	false	Depth of the parcel in metres
length	number	false	Length of the parcel in metres
width	number	false	Width of the parcel in metres.
label_number	string	false	Parcel number in the carrier system. This is used when the order is a tracking order, to match the parcel number in a carrier against the parcel recorded in shippit.

Response schema for products

Name	Type	Required	Description
title	string	false	conditional – Title or description of the product. Mandatory for international orders with specific couriers.
packed	integer	false	The number of products packed; used in partial orders, or otherwise when the number of products in the parcel is less than the total in the order. If not present, set to product quantity. If this is present, at least 1 item should have packed greater than 0. For international orders, all items should have packed greater than 0.
sku	string	false	conditional – Stock Keeping Unit (SKU) code of the product, for stock keeping purposes. Mandatory on international orders with specific couriers.
product_line_id	string	false	Product line associated with product. Like SKU, this is also for stock keeping purposes, and can be used when SKU would not be enough (e.g. an order containing multiple lines with the same SKU)
origin_country_code	string	false	Two-letter country code (ISO 3166-1 Alpha-2) for the product’s origin country. This is used in customs tracking for International shipments. Defaults to the home country of the Merchant.
location	string	false	Location of the product
dangerous_goods_code	string	false	This is the DG code required when making dangerous goods declarations. Before you can declare orders as having dangerous goods, you must first request for dangerous goods to enabled for your account. Contact Shippit Support or your account manager to have this enabled. DG surcharges are often charged on the weight of the order, so it is recommended to split your order into multiple orders if your order contains either: - both dangerous and non-dangerous goods, or - more than one dangerous goods code
dangerous_goods_text	string	false	Additional information related to dangerous goods being shipped
dangerous_goods_class	string	false	This is the DG class when making dangerous goods declarations.
tariff_code	string	false	Tariff or HS code for international orders declarations
quantity	integer	false	The number of products
price	number	false	Unit price of each product line item. Used in the packing slip and customs declarations.

Response schema for tracking_histories

Name	Type	Required	Description
status	string	true	The status of the order
timestamp	string	true	The date / time when the status change occurred.

Response schema for landed_cost

Name	Type	Required	Description
customs_duty	integer	false	The customs duty payable on the order
import_fee	integer	false	The import fee payable on the order
import_tax	integer	false	The import tax payable on the order
landed_cost_guaranteed	boolean	false	Has the landed cost guarantee been enabled for this order
incoterm	string	false	The incoterm to use for the order. For valid values, see International orders in the Developer guide.
receiver_freight_charge	decimal string	false	The receiver freight charge payable on the order
export_reason	string	false	The reason for exporting these goods. For valid values, see International orders in the Developer guide.

Response schema for user

Name	Type	Required	Description
email	string	true	The customer’s email address. Must match regular expression as defined in https://html.spec.whatwg.org/multipage/input.html#valid-e-mail-address
first_name	string	true	The customer’s first name. If last_name is not provided, then it is used as the customer’s full name.
last_name	string	false	The customer’s last name
mobile	string	false	Mobile number of the user who purchased the order. This could be different to the person receiving the order.

Response schema for documents

Name	Type	Required	Description
archive_awb	Array, see table	false	Archive Airway Bill
customs_invoice	Array, see table	false	Customs invoice. Generated for International orders.
dangerous_goods_declaration	Array, see table	false	Dangerous goods declaration - generated for orders that have dangerous goods properties specified.
packing_slip	Array, see table	false	Packing slip for the order.
shipping_label	Array, see table	false	Shipping label for the order. If the merchant account was configured to have the label and packing slip combined into a single document, the shipping_label prints the label only without the packing slip. If the merchant account was configured to enable ZPL output, can contain an encoded_label field containing ZPL output.

Response schema for document types

Name	Type	Required	Description
url	string	false	URL to a printable PDF document. This is a pre-signed URL, generated by the Shippit platform to provide access to a secured document. The pre-signed URL remains valid for 7 days. If you need to access this document after expiration, please make another request for a new URL to be issued.
page_size	string	false	none
file_type	string	false	File type of the label
encoded_label	string	false	If you have ZPL for your account, printable ZPL data for the document.