Label schemas

This section contains the schemas for the Label API.

Response schema for label

Name	Type	Required	Description
data	object	false	none
id	integer	false	The internal Shippit ID of the generated label
order	Array, see table	true	The order being labelled
qualified_url	string	true	URL to a printable label for the order. This is a pre-signed URL, generated by the Shippit platform to provide access to a secured label. The pre-signed URL remains valid for 7 days. If you need to access the label after it’s expired, make a new request to generate a new URL.

Response schema for order

Name	Type	Required	Description
tracking_number	string	true	Unique random ID assigned to an order. Use this as a reference for future API calls or support tickets.
slug	string	true	tracking_number in lowercase.
parcel_attributes	Array, see table	false	Represents a parcel attached to an order
products	Array, see table	false	An array of product items specified in the order. If no product information provided, this array is blank.
tracking_url	string	false	The URL of the customer tracking page for the order
return	boolean	false	Whether or not the order is a return order
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 carrier. In most cases, this is the same as the delivery_instructions passed into the request. Some carriers, however, have a specific format expected when sending delivery instructions through their API. This contains the actual delivery instructions that get sent through the carrier API when booked.
price	any	false	The price charged for the allocated order. If you’re creating orders by passing in courier_type, the carrier is usually not yet assigned at order creation and you get 0. Carrier allocation runs as a background process depending on the merchant preferences, available carriers, and quotes returned by the carriers, which can take a few seconds to complete after order creation. Shippit web users can also update the carrier in between API calls. Use the label call to retrieve the final carrier and quoted price. If the quoted price is still 0 during the label call, something could have gone wrong with the carrier selection, and you might need to amend the order.
customs_documents_require_printing	boolean	false	Whether or not to print customs documents, such as declarations or invoices for including with the shipment. By default this is true for International orders.
courier_type	string	false	The carrier allocated to the order. See the create order courier_allocation API for available keywords.
tracking_histories	Array, see table	false	An array of tracking history statuses shown to the recipient as part of the order history on the tracking page
state	string	false	The state of the order as progressed by the merchant
user	Array, see table	false	The recipient of the order
documents	Array, see table	true	Documents attached to the label response
order_attachments	Array, see table	false	Additional attachments related to the order, such as certificates of origin or other supporting documents
courier_job_id	string	false	The ID assigned by the carrier to the shipment, if provided

Response schema for parcel_attributes

Name	Type	Required	Description
qty	number	false	The number of parcels specified by the entry. Depending on the configuration of the merchant account, the number of parcels generated might 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 you have enabled Allocate each item in an order to a separate carton, 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. 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 carriers.
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 one item should have packed greater than 0. For international orders, all items should have packed greater than 0.
sku	string	false	conditional: SKU of the product. Mandatory on international orders for some carriers.
product_line_id	string	false	Product line ID associated with product. Optional, for use when SKU isn’t a unique identifier, such as when you have multiple lines containing 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, contact Shippit Support to have dangerous goods enabled for your account. Surcharges are often charged on the weight of the order; to avoid this, split your order into multiple orders if your order contains both dangerous and non-dangerous goods, or uses more than one dangerous goods code.
dangerous_goods_text	string	false	Additional information related to dangerous goods being shipped
dangerous_goods_class	string	false	The dangerous goods class
tariff_code	string	false	Tariff or HS code for international orders declarations
quantity	integer	false	The number of products ordered
price	number	false	Unit price of each product line item. Used in the packing slip and customs declarations.
status	string	true	The status of the order
timestamp	string	true	The date/time when the status change occurred.

Response schema for user

Name	Type	Required	Description
email	string	true	The customer’s email address. Must match the regular expression defined in WHATWG HTML spec.
first_name	string	true	The customer’s first name. Used as the customer’s full name if last_name isn’t provided.
last_name	string	false	The customer’s last name
mobile	string	false	Mobile number of the user who purchased the order. This might be different to the recipient’s phone number.

Response schema for documents

Name	Type	Required	Description
archive_awb	object	false	Archive Airway Bill
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 label. The pre-signed URL remains valid for 7 days. If you need to access the label after it’s expired, make a new request to generate a new URL.
page_size	string	false
file_type	string	false	File type of the label
encoded_label	string	false	Printable ZPL data for the document, if available

Response schema for order_attachments

Name	Type	Required	Description
invoice	object, see table	false	Invoice document related to the order
customs_document	object, see table	false	Customs documentation for international shipments
msds	object, see table	false	Material Safety Data Sheet for hazardous goods
drop_ball_test	object, see table	false	Drop ball test certification document
survey_report	object, see table	false	Survey report documentation
health_permit	object, see table	false	Health permit documentation
fda_license	object, see table	false	FDA license documentation
certificate_of_origin	object, see table	false	Certificate of origin document for international shipments
import_permit	object, see table	false	Import permit documentation

Response schema for attachment document

Name	Type	Required	Description
url	string	false	URL to a printable document. This is a pre-signed URL, generated by the Shippit platform to provide access to a secured label. The pre-signed URL remains valid for 7 days. If you need to access the label after it’s expired, make a new request to generate a new URL.