Shippit (3.0.20220623)

Download OpenAPI specification:Download

The following documentation describes the current Shippit API (version 3).

Quote

The Quote API will return a quote given a destination location and parcel attributes.

Retrieve Quote

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.

Authorizations:
AuthToken
Request Body schema: application/json
required
object (Root Type for quote)

A specification of the queries to include in the quote.

dropoff_postcode
required
string

destination postcode for the quote

dropoff_state
string

destination state for the quote. Required when dropoff_postcode is unassigned or set to AU

dropoff_suburb
required
string

The dropoff suburb

required
Array of objects (Parcel)

An array of parcel specifications to be included in the quote.

Each item can be used to specify the qty, dimensions, and other information about the products to be shipped, and the parcel used to ship it.

At minimum, only the qty and weight fields are required. There is a maximum of 1000 parcels per quote request.

Array
weight
number

Weight of the parcel in kilos.

depth
number

Depth of the parcel in metres

length
number

Length of the parcel in metres

width
number

Width of the parcel in metres.

label_number
string

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

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.

Array of objects

An array of product details to be included in the quote

Array
title
string

Title or description of the product

tariff_code
string

Tariff code for international orders declarations

quantity
integer

The number of products

price
number

Unit price of each product line item. Used to calculate duties and taxes

order_date
string <date>

delivery date for the order, required for priority orders

return_all_quotes
boolean

If set to true, the system returns all quotes instead of cheapest/fastest quote. Defaults to false.

dutiable_amount
number

conditional Declared value for customs when shipping international.

Mandatory for International orders.

product_currency
string

Three letter ISO 4217 currency code that applies to the products which will be used for customs.

dropoff_country_code
string

The destination country code for the quote in ISO 3166 Alpha-2 format. If unassigned, defaults to the country code of the merchant's primary location, or otherwise 'AU'

dropoff_address
string

The dropoff address for the quote. Mandatory for OnDemand orders.

service_levels
Array of strings

An array of service leves to return quotes for. Valid values include:

  • standard
  • express
  • priorty
  • on_demand
features
Array of strings

Some carriers provide add-on services (features) which can be indicated when requesting a quote. These services are identified by a unique string and will depend on the carrier. To request these services, add a string to these field. Services supported at the moment:

  • white_glove (Neway, DesignerTransport): A delivery service that offers more personalised and tailored services for shipping high value, large or fragile goods.
  • calculate_ddp (SmartRoutingInternational): When requested, the returned quote prices are inclusive of import taxes, duties and fees.
authority_to_leave
string

If set to "Yes", the system returns all quotes where Authority to Leave is enabled.

Responses

Response Schema: application/json
Array of objects (Root Type for Quote)

The Quote returned by the carrier

Array
courier_type
string

The name of the courier or service level giving the quote.

error
string

Error response, if any, received from the carrier(s) during quoting.

Array of objects (Root Type for Quote)

List of quotes returned for the service level or carrier.

Array
delivery_date
string <date>

Estimated date of delivery for the order

delivery_window
string

For priority orders, machine-readable estimated range of times when the delivery could take place.

delivery_window_desc
string

For priority orders, human-readable estimated range of times when the delivery could take place.

price
number

Amount quoted by the carrier.

courier_type
string

optional If returned inside a quote response for a service level (e.g. standard), the carrier returning the quote. May be omitted if a specific carrier was requested.

customs_duty
number

Customs duty component for international orders, if applicable. This amount is included in the price if the carrier is configured to return a DDP quote.

import_tax
number

Import tax component for international orders, if applicable. This amount is included in the price if the carrier is configured to return a DDP quote.

import_fee
number

Import fees component for international orders, if applicable. This amount is included in the price if the carrier is configured to return a DDP quote.

incoterm
any

A universal term of trade that defines the responsibility and obligations with the transport of goods. Most commonly used to indicate the responsible party for payment of duties and taxes.

estimated_transit_time
string

Estimated amount of time for the quote to arrive.

service_level
string

The service level associated with this quote or group of quotes.

success
boolean

Whether or not this service level was able to obtain a valid quote from the carrier(s).

count
number

Number of quote results returned.

Request samples

Content type
application/json
Example
{
  • "quote": {
    }
}

Response samples

Content type
application/json
Example
{
  • "response": [
    ],
  • "count": 4
}

Order

The Order API will submit an order to Shippit

Create an Order

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.

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
Authorizations:
AuthToken
Request Body schema: application/json

Passes an Order object under the order field.

required
object (OrderRequestOrder)

Represents parameters that can be used to create an order in Shippit

required
Array of objects (Root Type for ParcelAttributes)

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 ech item in an order to a separate carton setting is enabled in the Shippit administration page, then each item will be 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 will be specified in entries there, separate from the parcel information. In which case each parcel entry represents a single parcel.

Array
title
string

conditional -- Title or description of the product. Mandatory for international orders with specific couriers.

packed
integer

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

conditional -- Stock Keeping Unit (SKU) code of the product, for stock keeping purposes. Mandatory on international orders with specific couriers.

product_line_id
string

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

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

Location of the product

dangerous_goods_code
string

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

Additional information related to dangerous goods being shipped

dangerous_goods_class
string

This is the DG class when making dangerous goods declarations.

price
number

Unit price of each product line item. Used in the packing slip and customs declarations.

weight
number

Weight of the parcel in kilos.

depth
number

Depth of the parcel in metres

length
number

Length of the parcel in metres

width
number

Width of the parcel in metres.

label_number
string

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

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.

Array of objects (Product)

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.

Array
title
string

conditional -- Title or description of the product. Mandatory for international orders with specific couriers.

packed
integer

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

conditional -- Stock Keeping Unit (SKU) code of the product, for stock keeping purposes. Mandatory on international orders with specific couriers.

product_line_id
string

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

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

Location of the product

dangerous_goods_code
string

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

Additional information related to dangerous goods being shipped

dangerous_goods_class
string

This is the DG class when making dangerous goods declarations.

tariff_code
string

Tariff code for International orders declarations

quantity
integer

The number of products ordered.

price
number

Unit price of each product line item. Used in the packing slip and customs declarations.

authority_to_leave
string

whether or not the order can be left unattended at the delivery address, options are Yes or No

cash_on_delivery_amount
number

Used by some carriers (e.g. NinjaVan) to indicate amount to be received on delivery for cash on delivery orders.

courier_type
string

The service level for the order, valid options are standard, express, priority, click_and_collect. If you use courier_type in your request, then Shippit will allocate the courier for the job at that service level. If you want to specify the courier in the request please use courier_allocation attribute instead.

One of courier_allocation or courier_type is required. If omitted or invalid option is provided in the request, we will allocate an enabled courier that matches the default service level. The default service level is standard and can be configured by Shippit on request for a merchant. The available service level options are standard, express and priority.

receiver_contact_number
string

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

name of the person receiving the order if different than the user who purchased the order

retailer_invoice
string

Merchant invoice number - the customer-facing sales order reference of the order. This would be what the recipient sees on the shipping label, packslip, customs declaration, receipt, etc.

retailer_reference
string

Merchant reference id - if the merchant uses a separate internal reference id for the order, it can be placed here.

courier_allocation
string

For courier_allocation, the list of valid options are outlined below.

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

One of courier_allocation or courier_type is required.

If omitted or invalid option is provided in the request, we will allocate an enabled courier that matches the default service level. The default service level is standard and can be configured by Shippit on request for a merchant. The available service level options are standard, express and priority.

courier_allocaiton is required when tracking_only is set to true

receiver_language_code
string

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

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 will be returned.
product_currency
string

Three letter ISO 4217 currency code that applies to the order, which will be sent to the carrier and presented on the customs invoice. Defaults to AUD

suppress_communications
boolean

if true, all notifications will be suppressed for this specific order

tracking_only
boolean

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.

Array of objects (Order Request TrackingHistory)

An array of Tracking History statuses that are are shown to the recipient as part of the order's history on the tracking page.

Array
timestamp
required
string <date-time>

expected format: ISO-8601 datetime, such as YYYY-MM-DDThh:mm or YYYY-MM-DDThh:mm:ss+TZ.

The date-time when the status change occurred.

status
required
string

The status of the order

object (Root Type for UserAttributes)

Represents the customers details attached to the order.

email
required
string

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
required
string

the customer's first name. If last_name is not provided, then it is used as the customer's full name.

last_name
string

customer's last name

mobile
string

Mobile number of the user / receiver.

features
Array of strings

Some carriers provide add-on services (features) which can be indicated in the order. These services are identified by a unique string and will depend on the carrier. To request these services, add a string to these field. Services supported at the moment:

  • white_glove (Neway, DesignerTransport): A delivery service that offers more personalised and tailored services for shipping high value, large or fragile goods.
  • calculate_ddp (SmartRoutingInternational): When requested, the returned quote prices are inclusive of import taxes, duties and fees.
customer_shipping_fee_paid
string

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 will be displayed on the commercial invoice.

description
string

Goods description for the order. May appear in labels for international orders. If not provided, defaults to the type of goods setting of the merchant account. Description is mandatory for international orders when validate is set to true.

duties
number

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 will be displayed on the commercial invoice. eg: 12.90

tax_amount
number

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 will be displayed separately on the commercial invoice. eg: 2.39

object (Root Type for OrderRequestOrderCustomsClearanceAttribute)

Represents customs clearance parameters for international orders.

tax_id_type
string <= 10 characters

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 <= 2 characters

The issuing country of the tax id number in in ISO 3166 Alpha-2 format. eg. GB for Great Britain

tax_id_number
string <= 15 characters

The tax id number that is declared against this order.

incoterm
string <= 10 characters

A universal term of trade that defines the responsibility and obligations with the transport of goods. Most commonly used to indicate the responsible party for payment of duties and taxes. Valid values include:

  • DDU
  • DDP
  • EXW
  • FCA
  • CPT
  • CFR
  • CIP
  • CIF
  • DAF
  • DAT
  • DAP
  • DPU
  • DES
  • DEQ
  • FAS
  • FOB
export_reason
string <= 40 characters

A term used to indicate the reason for export of dutiable goods. Selected options can affect how your shipment is cleared and how much tax is imposed on your shipment during customs clearance. Example values:

  • Permanent
  • Temporary
  • Return For Repair
  • Used Exhibition Goods To Origin
  • Intercompany Use
  • Commercial Purpose Or Sale
  • Personal Belongings or Personal Use
  • Sample
  • Gift
  • Return To Origin
  • Warranty Replacement
  • Diplomatic Goods
  • Defence Material
recipient_id
string <= 20 characters

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

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.

pickup_postcode
string

Pickup postcode for the return order

* required for return orders

pickup_address
string

Pickup address for the return order

* required for return orders

pickup_suburb
string

Pickup suburb for the return order

* required for return orders

pickup_state
string

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

Whether the order being passed is a return order or not

delivery_address
required
string

delivery address for the order

delivery_postcode
required
string

delivery postcode for the order

delivery_state
required
string

delivery state for the order Australian States valid options are NSW, QLD, ACT, WA, NT, SA, VIC, TAS

delivery_suburb
required
string

delivery suburb for the order

delivery_instructions
string

special delivery instructions for the order, limited to 55 characters

delivery_date
string <date>

The date of the order for priority orders.

The recommended format is in ISO-8601 YYYY-MM-DD, although the Shippit is flexible enough to parse YYYY/MM/DD.

conditional -- specifies the date of the order for priority orders

delivery_date must be in the future.

delivery_window
string

expected format: 00:00-00:00

conditional -- specifies the time window of the order, to be used when sending a priority order

delivery_window must be in the future.

courier_job_id
string

Used in tracking_order's, the ID assigned by some carriers to the shipment / consignment.

delivery_country_code
string

The destination country code for the order in ISO 3166 Alpha-2 format. If unassigned, defaults to the country code of the merchant's primary location, or otherwise 'AU'.

delivery_district_city
string

Used in some countries to add additional district city information in addition to the delivery_suburb and delivery_state. Most of this time this is determined using the delivery_suburb and delivery_postcode.

Responses

Response Schema: application/json
object (OrderResponseOrder)

Represents an Order that was created in Shippit

tracking_number
required
string

Unique random ID assigned by Shippit to an order. This can be used as a reference for future API calls or support tickets.

slug
required
string

tracking_number in lowercase.

object (Order Response Parcel specification)

Represents a parcel attached to an order.

qty
number

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 will try 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 will generate one parcel entry for each parcel entry sent in.

weight
number

Weight of the parcel in kilos.

depth
number

Depth of the parcel in metres

length
number

Length of the parcel in metres

width
number

Width of the parcel in metres.

label_number
string

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.

Array of objects (Product)

An array of product items specified in the order.

If product information was not provided, this array will be blank.

Array
title
string

conditional -- Title or description of the product. Mandatory for international orders with specific couriers.

packed
integer

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

conditional -- Stock Keeping Unit (SKU) code of the product, for stock keeping purposes. Mandatory on international orders with specific couriers.

product_line_id
string

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

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

Location of the product

dangerous_goods_code
string

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

Additional information related to dangerous goods being shipped

dangerous_goods_class
string

This is the DG class when making dangerous goods declarations.

tariff_code
string

Tariff code for International orders declarations

quantity
integer

The number of products ordered.

price
number

Unit price of each product line item. Used in the packing slip and customs declarations.

tracking_url
string

The URL of the order's customer tracking page.

return
boolean

Whether or not the order is a return order.

id
integer

Shippit internal numerical ID

processing_state
string

Internal order status set and progressed by Shippit upon creation.

invoice_number
any

Internal link between an order and a Shippit invoice - will almost always be null on order creation.

courier_delivery_instructions
string

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 will contain the actual delivery instructions that get sent through the courier API when booked.

courier_name
string

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 will usually not be yet be assigned at order creation and you will get null. Courier allocation will be 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 will reflect 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

The price that will be charged for the allocated order.

If you're creating orders by passing in courier_type, the courier will usually not be yet be assigned at order creation and you will get 0. Courier allocation will be 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

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

The courier allocated to the order. See the ORDER CREATE courier_allocation API for available keywords.

tracking_histories
Array of objects (OrderResponseTrackingHistory)

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

The state of the order as progressed by the merchant.

object (Root Type for UserAttributes)

Represents the customers details attached to the order.

email
required
string

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
required
string

the customer's first name. If last_name is not provided, then it is used as the customer's full name.

last_name
string

customer's last name

mobile
string

Mobile number of the user / receiver.

required
object (OrderResponseOrderDocumentsHash)

A keyword hash of documents generated for an order. Usually populated during the LABEL call.

object (Root Type for LabelDocument)

A Label or document in the Labels API, representing a printable document available on a public URL.

url
string

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
file_type
string

File type of the label

encoded_label
string

If you have ZPL for your account, printable ZPL data for the document.

object (Root Type for LabelDocument)

A Label or document in the Labels API, representing a printable document available on a public URL.

url
string

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
file_type
string

File type of the label

encoded_label
string

If you have ZPL for your account, printable ZPL data for the document.

object (Root Type for LabelDocument)

A Label or document in the Labels API, representing a printable document available on a public URL.

url
string

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
file_type
string

File type of the label

encoded_label
string

If you have ZPL for your account, printable ZPL data for the document.

object (Root Type for LabelDocument)

A Label or document in the Labels API, representing a printable document available on a public URL.

url
string

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
file_type
string

File type of the label

encoded_label
string

If you have ZPL for your account, printable ZPL data for the document.

object (Root Type for LabelDocument)

A Label or document in the Labels API, representing a printable document available on a public URL.

url
string

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
file_type
string

File type of the label

encoded_label
string

If you have ZPL for your account, printable ZPL data for the document.

delivery_address
required
string

delivery address for the order

delivery_postcode
required
string

delivery postcode for the order

delivery_state
required
string

delivery state for the order Australian States valid options are NSW, QLD, ACT, WA, NT, SA, VIC, TAS

delivery_suburb
required
string

delivery suburb for the order

delivery_instructions
string

special delivery instructions for the order, limited to 55 characters

receiver_contact_number
string

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

name of the person receiving the order if different than the user who purchased the order

retailer_invoice
string

Merchant invoice number - the customer-facing sales order reference of the order. This would be what the recipient sees on the shipping label, packslip, customs declaration, receipt, etc.

receiver_language_code
string

Two-letter ISO 639-1 language code of the recipient. Used to determine the language of tracking notifications and other communications. Defaults to EN

delivery_date
string <date>

The date of the order for priority orders.

The recommended format is in ISO-8601 YYYY-MM-DD, although the Shippit is flexible enough to parse YYYY/MM/DD.

conditional -- specifies the date of the order for priority orders

delivery_date must be in the future.

delivery_window
string

expected format: 00:00-00:00

conditional -- specifies the time window of the order, to be used when sending a priority order

delivery_window must be in the future.

courier_job_id
string

Used in tracking_order's, the ID assigned by some carriers to the shipment / consignment.

delivery_country_code
string

The destination country code for the order in ISO 3166 Alpha-2 format. If unassigned, defaults to the country code of the merchant's primary location, or otherwise 'AU'.

delivery_district_city
string

Used in some countries to add additional district city information in addition to the delivery_suburb and delivery_state. Most of this time this is determined using the delivery_suburb and delivery_postcode.

Request samples

Content type
application/json
Example
{
  • "order": {
    }
}

Response samples

Content type
application/json
Example
{
  • "response": {
    }
}

Cancel an Order

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.

Authorizations:
AuthToken
path Parameters
tracking_number
required
string

The tracking number of the Order.

Responses

Response Schema: application/json
object (OrderResponseOrder)

Represents an Order that was created in Shippit

tracking_number
required
string

Unique random ID assigned by Shippit to an order. This can be used as a reference for future API calls or support tickets.

slug
required
string

tracking_number in lowercase.

object (Order Response Parcel specification)

Represents a parcel attached to an order.

qty
number

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 will try 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 will generate one parcel entry for each parcel entry sent in.

weight
number

Weight of the parcel in kilos.

depth
number

Depth of the parcel in metres

length
number

Length of the parcel in metres

width
number

Width of the parcel in metres.

label_number
string

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.

Array of objects (Product)

An array of product items specified in the order.

If product information was not provided, this array will be blank.

Array
title
string

conditional -- Title or description of the product. Mandatory for international orders with specific couriers.

packed
integer

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

conditional -- Stock Keeping Unit (SKU) code of the product, for stock keeping purposes. Mandatory on international orders with specific couriers.

product_line_id
string

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

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

Location of the product

dangerous_goods_code
string

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

Additional information related to dangerous goods being shipped

dangerous_goods_class
string

This is the DG class when making dangerous goods declarations.

tariff_code
string

Tariff code for International orders declarations

quantity
integer

The number of products ordered.

price
number

Unit price of each product line item. Used in the packing slip and customs declarations.

tracking_url
string

The URL of the order's customer tracking page.

return
boolean

Whether or not the order is a return order.

id
integer

Shippit internal numerical ID

processing_state
string

Internal order status set and progressed by Shippit upon creation.

invoice_number
any

Internal link between an order and a Shippit invoice - will almost always be null on order creation.

courier_delivery_instructions
string

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 will contain the actual delivery instructions that get sent through the courier API when booked.

courier_name
string

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 will usually not be yet be assigned at order creation and you will get null. Courier allocation will be 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 will reflect 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

The price that will be charged for the allocated order.

If you're creating orders by passing in courier_type, the courier will usually not be yet be assigned at order creation and you will get 0. Courier allocation will be 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

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

The courier allocated to the order. See the ORDER CREATE courier_allocation API for available keywords.

tracking_histories
Array of objects (OrderResponseTrackingHistory)

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

The state of the order as progressed by the merchant.

object (Root Type for UserAttributes)

Represents the customers details attached to the order.

email
required
string

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
required
string

the customer's first name. If last_name is not provided, then it is used as the customer's full name.

last_name
string

customer's last name

mobile
string

Mobile number of the user / receiver.

required
object (OrderResponseOrderDocumentsHash)

A keyword hash of documents generated for an order. Usually populated during the LABEL call.

object (Root Type for LabelDocument)

A Label or document in the Labels API, representing a printable document available on a public URL.

url
string

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
file_type
string

File type of the label

encoded_label
string

If you have ZPL for your account, printable ZPL data for the document.

object (Root Type for LabelDocument)

A Label or document in the Labels API, representing a printable document available on a public URL.

url
string

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
file_type
string

File type of the label

encoded_label
string

If you have ZPL for your account, printable ZPL data for the document.

object (Root Type for LabelDocument)

A Label or document in the Labels API, representing a printable document available on a public URL.

url
string

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
file_type
string

File type of the label

encoded_label
string

If you have ZPL for your account, printable ZPL data for the document.

object (Root Type for LabelDocument)

A Label or document in the Labels API, representing a printable document available on a public URL.

url
string

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
file_type
string

File type of the label

encoded_label
string

If you have ZPL for your account, printable ZPL data for the document.

object (Root Type for LabelDocument)

A Label or document in the Labels API, representing a printable document available on a public URL.

url
string

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
file_type
string

File type of the label

encoded_label
string

If you have ZPL for your account, printable ZPL data for the document.

delivery_address
required
string

delivery address for the order

delivery_postcode
required
string

delivery postcode for the order

delivery_state
required
string

delivery state for the order Australian States valid options are NSW, QLD, ACT, WA, NT, SA, VIC, TAS

delivery_suburb
required
string

delivery suburb for the order

delivery_instructions
string

special delivery instructions for the order, limited to 55 characters

receiver_contact_number
string

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

name of the person receiving the order if different than the user who purchased the order

retailer_invoice
string

Merchant invoice number - the customer-facing sales order reference of the order. This would be what the recipient sees on the shipping label, packslip, customs declaration, receipt, etc.

receiver_language_code
string

Two-letter ISO 639-1 language code of the recipient. Used to determine the language of tracking notifications and other communications. Defaults to EN

delivery_date
string <date>

The date of the order for priority orders.

The recommended format is in ISO-8601 YYYY-MM-DD, although the Shippit is flexible enough to parse YYYY/MM/DD.

conditional -- specifies the date of the order for priority orders

delivery_date must be in the future.

delivery_window
string

expected format: 00:00-00:00

conditional -- specifies the time window of the order, to be used when sending a priority order

delivery_window must be in the future.

courier_job_id
string

Used in tracking_order's, the ID assigned by some carriers to the shipment / consignment.

delivery_country_code
string

The destination country code for the order in ISO 3166 Alpha-2 format. If unassigned, defaults to the country code of the merchant's primary location, or otherwise 'AU'.

delivery_district_city
string

Used in some countries to add additional district city information in addition to the delivery_suburb and delivery_state. Most of this time this is determined using the delivery_suburb and delivery_postcode.

Response samples

Content type
application/json
{
  • "response": {
    }
}

Get Label information for an Order

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.

Authorizations:
AuthToken
path Parameters
tracking_number
required
string

The tracking number of the Order.

Responses

Response Schema: application/json
object (Root Type for Label)

Represents an Order and related labelling information

data
object
id
integer <invalid>

Shippit internal ID of the generated label.

required
object (LabelResponseOrder)

Represents an Order that is returned in Label response

tracking_number
required
string

Unique random ID assigned by Shippit to an order. This can be used as a reference for future API calls or support tickets.

slug
required
string

tracking_number in lowercase.

object (Order Response Parcel specification)

Represents a parcel attached to an order.

qty
number

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 will try 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 will generate one parcel entry for each parcel entry sent in.

weight
number

Weight of the parcel in kilos.

depth
number

Depth of the parcel in metres

length
number

Length of the parcel in metres

width
number

Width of the parcel in metres.

label_number
string

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.

Array of objects (Product)

An array of product items specified in the order.

If product information was not provided, this array will be blank.

Array
title
string

conditional -- Title or description of the product. Mandatory for international orders with specific couriers.

packed
integer

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

conditional -- Stock Keeping Unit (SKU) code of the product, for stock keeping purposes. Mandatory on international orders with specific couriers.

product_line_id
string

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

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

Location of the product

dangerous_goods_code
string

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

Additional information related to dangerous goods being shipped

dangerous_goods_class
string

This is the DG class when making dangerous goods declarations.

tariff_code
string

Tariff code for International orders declarations

quantity
integer

The number of products ordered.

price
number

Unit price of each product line item. Used in the packing slip and customs declarations.

tracking_url
string

The URL of the order's customer tracking page.

return
boolean

Whether or not the order is a return order.

id
integer

Shippit internal numerical ID

processing_state
string

Internal order status set and progressed by Shippit upon creation.

invoice_number
any

Internal link between an order and a Shippit invoice - will almost always be null on order creation.

courier_delivery_instructions
string

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 will contain the actual delivery instructions that get sent through the courier API when booked.

price
any

The price that will be charged for the allocated order.

If you're creating orders by passing in courier_type, the courier will usually not be yet be assigned at order creation and you will get 0. Courier allocation will be 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

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

The courier allocated to the order. See the ORDER CREATE courier_allocation API for available keywords.

tracking_histories
Array of objects (OrderResponseTrackingHistory)

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

The state of the order as progressed by the merchant.

object (Root Type for UserAttributes)

Represents the customers details attached to the order.

email
required
string

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
required
string

the customer's first name. If last_name is not provided, then it is used as the customer's full name.

last_name
string

customer's last name

mobile
string

Mobile number of the user / receiver.

required
object (OrderResponseOrderDocumentsHash)

A keyword hash of documents generated for an order. Usually populated during the LABEL call.

object (Root Type for LabelDocument)

A Label or document in the Labels API, representing a printable document available on a public URL.

url
string

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
file_type
string

File type of the label

encoded_label
string

If you have ZPL for your account, printable ZPL data for the document.

object (Root Type for LabelDocument)

A Label or document in the Labels API, representing a printable document available on a public URL.

url
string

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
file_type
string

File type of the label

encoded_label
string

If you have ZPL for your account, printable ZPL data for the document.

object (Root Type for LabelDocument)

A Label or document in the Labels API, representing a printable document available on a public URL.

url
string

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
file_type
string

File type of the label

encoded_label
string

If you have ZPL for your account, printable ZPL data for the document.

object (Root Type for LabelDocument)

A Label or document in the Labels API, representing a printable document available on a public URL.

url
string

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
file_type
string

File type of the label

encoded_label
string

If you have ZPL for your account, printable ZPL data for the document.

object (Root Type for LabelDocument)

A Label or document in the Labels API, representing a printable document available on a public URL.

url
string

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
file_type
string

File type of the label

encoded_label
string

If you have ZPL for your account, printable ZPL data for the document.

courier_job_id
string

The ID assigned by some carriers to the shipment/consignment.

qualified_url
required
string

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 this label after expiration, please make another request for a new URL to be issued.

Response samples

Content type
application/json
{}

Merchant

The merchant settings API will allow you to query the current settings for your merchant account and to make updates to this via API.

Get Merchant settings

Authorizations:
AuthToken

Responses

Response Schema: application/json
object (Root Type for Merchant)

Represents a merchant account

store_name
string
company_name
string
contact_name
string
contact_phone
string
shipping_cart_method_name
string
preparation_time
integer <int32>
website_url
string
address_1
string
suburb
string
state
string
postcode
string

Response samples

Content type
application/json
{
  • "response": {
    }
}

Update Merchant settings

Given an object with the desired settings to update, will update the Merchant settings on Shippit

Request Body schema: application/json
required
object (Root Type for Merchant)

Represents a merchant account

store_name
string
company_name
string
contact_name
string
contact_phone
string
shipping_cart_method_name
string
preparation_time
integer <int32>
website_url
string
address_1
string
suburb
string
state
string
postcode
string

Responses

Response Schema: application/json
object (Root Type for Merchant)

Represents a merchant account

store_name
string
company_name
string
contact_name
string
contact_phone
string
shipping_cart_method_name
string
preparation_time
integer <int32>
website_url
string
address_1
string
suburb
string
state
string
postcode
string

Request samples

Content type
application/json
{
  • "merchant": {
    }
}

Response samples

Content type
application/json
{
  • "response": {
    }
}

Track

The Track API will allow you to request tracking information or subscribe to our webhook.

Track Order

This sends a tracking request to the API to retrieve the status of an Order.

This uses a pull-based model of Order tracking, which sends tracking info on each request. If you would like to use a push-based model where you automatically receive messages on Order status changes, you can subscribe to the Tracking Webhook instead.

path Parameters
tracking_number
required
string

The tracking number of the Order

Responses

Response Schema: application/json
object (Root Type for TrackingResponseOrder)

Order details returned by a tracking request

tracking_number
string

Tracking number of the Order

tracking_url
string

URL presenting tracking info for the Order. This can be shown to the recipient to give them status updates on the Order.

success
boolean

Whether or not this tracking request was successful - should always be true as tracking errors will be returned at the top-level response.

error
string

Errors associated with the tracking request - should always be null as tracking errors will be returned at the top-level response.

Array of objects (TrackingResponseTrackingHistory)

A list of historical tracking statuses for the Order. This will at minimum list the order status, along with the date and time when it changed, and who was responsible for the status change.

Array
date
required
string <date>

The ISO-8601 date as YYYY-MM-DD when the event happened.

status_owner
required
string

The party responsible for the status change.

timestamp
required
string

The time in HH:MM:SS that the tracking event happened.

status
required
string

The status of the order

Response samples

Content type
application/json
{
  • "response": {
    }
}

Webhook

Shippit will send status updates on orders to a URL you have configured in the Shippit admin page.

This can be configured at Settings -> Integrations -> Webhook URL at the Shippit admin.

If configured, Shippit will send POST requests to the URL set here with updates on an Order's status as it progresses.


Best practices for using webhooks

Event types

Your webhook implementation should be configured to action only the types of events required by your integration. Actioning for extra events (or all events) is not recommended as we may add new events at anytime

Handle duplicate events

Webhook endpoints might occasionally receive the same event more than once. We advise you to guard against duplicated event receipts by making your event processing idempotent. One way of doing this is logging the events you’ve processed, and then not processing already-logged events.

Order of events

Shippit does not guarantee delivery of events in the order in which they are generated.

IP allow list

The webhook will originate from one of the following IP addresses:

  • 13.210.185.17
  • 54.153.239.182 [New]
  • 54.66.78.172 [New]
  • 13.237.179.89
  • 13.239.82.79
  • 54.66.178.150

It is recommended to only allow requests from these IP addresses as part of your firewall configuration.

Request Body schema: application/json

Updated status info about the Order sent by the webhook.

tracking_number
string
tracking_url
string
current_state
string

Possible enumerations are await_collection, awaiting_collection, awaiting_drop_off, cancelled, completed, parcel_completed, partially_completed, customs_awaiting_paym, customs_failed, customs_on_hold, damaged, delivery_attempted, delivery_failed, in_transit, insufficient_address, invalidated, lost, pickup_failed, processing, ready_for_pickup, return_booked, return_booking_failed, return_requested, returned_to_sender, untrackable, with_customs, with_driver

retailer_order_number
string
courier_name
string
courier_job_id
string
delivery_address
string
delivery_suburb
string
delivery_postcode
string
delivery_state
string
merchant_url
string
Array of objects
Array
status
string
time
string <date-time>
Array of objects
Array
quantity
integer <int32>
sku
string
title
string
product_line_id
string

Responses

Request samples

Content type
application/json
{
  • "tracking_number": "PPYvZCTod5bkD",
  • "current_state": "completed",
  • "retailer_order_number": "WEYFEW232",
  • "courier_name": "Couriers Please",
  • "courier_job_id": "CPAVZUZ0001749",
  • "delivery_address": "123 Fake Drive",
  • "delivery_suburb": "Sydney",
  • "delivery_postcode": "2000",
  • "delivery_state": "NSW",
  • "merchant_url": "myshopify.storename.com",
  • "status_history": [
    ],
  • "products": [
    ]
}

Book

The book API initiates a booking with the respective carriers.

Book Order

Given an array of Orders, this will initiate a booking with their respective couriers.

For Orders to be booked, they must first be labelled.

Authorizations:
AuthToken
Request Body schema: application/json

An array of Order tracking numbers to book

orders
required
Array of strings

an array of Shippit tracking numbers, corresponding to the orders which you would like to book.

Responses

Response Schema: application/json
Array of objects (Root Type for BookingStatus)

Array of booking statuses at each courier

Array
courier
string

The courier where the booking was made

manifest
string

The Manifest ID of the booking

manifest_pdf
string

A URL to a printable copy of the shipping manifest. 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.

order_count
integer <int32>

How many orders were included in this manifest.

success
boolean

Whether or not the booking succeeded

orders
Array of strings

An array of order tracking numbers included in this status. Used to indicate which orders failed to manifest in the case where success = false.

error
string

Error code that applies to the individual bookings / orders referenced.

error_description
string

Human-readable error message applied to the individual bookings / orders referenced.

error
string

Error code returned by Shippit

For the book response, there can be errors at the top-level request or for individual orders booked.

If the error occurs at the top-level request (order format, authorization), then this error code applies. Otherwise, the response will be successful and there will be individual errors applied in the body of each booked item.

error_description
string

Human-readable description of the top-level error encountered.

count
integer

Number of items in the response

Request samples

Content type
application/json
{
  • "orders": [
    ]
}

Response samples

Content type
application/json
Example
{}

Label

The label API will return a URL to a label for an order.

Get Label information for an Order

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.

Authorizations:
AuthToken
path Parameters
tracking_number
required
string

The tracking number of the Order.

Responses

Response Schema: application/json
object (Root Type for Label)

Represents an Order and related labelling information

data
object
id
integer <invalid>

Shippit internal ID of the generated label.

required
object (LabelResponseOrder)

Represents an Order that is returned in Label response

tracking_number
required
string

Unique random ID assigned by Shippit to an order. This can be used as a reference for future API calls or support tickets.

slug
required
string

tracking_number in lowercase.

object (Order Response Parcel specification)

Represents a parcel attached to an order.

qty
number

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 will try 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 will generate one parcel entry for each parcel entry sent in.

weight
number

Weight of the parcel in kilos.

depth
number

Depth of the parcel in metres

length
number

Length of the parcel in metres

width
number

Width of the parcel in metres.

label_number
string

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.

Array of objects (Product)

An array of product items specified in the order.

If product information was not provided, this array will be blank.

Array
title
string

conditional -- Title or description of the product. Mandatory for international orders with specific couriers.

packed
integer

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

conditional -- Stock Keeping Unit (SKU) code of the product, for stock keeping purposes. Mandatory on international orders with specific couriers.

product_line_id
string

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

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

Location of the product

dangerous_goods_code
string

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

Additional information related to dangerous goods being shipped

dangerous_goods_class
string

This is the DG class when making dangerous goods declarations.

tariff_code
string

Tariff code for International orders declarations

quantity
integer

The number of products ordered.

price
number

Unit price of each product line item. Used in the packing slip and customs declarations.

tracking_url
string

The URL of the order's customer tracking page.

return
boolean

Whether or not the order is a return order.

id
integer

Shippit internal numerical ID

processing_state
string

Internal order status set and progressed by Shippit upon creation.

invoice_number
any

Internal link between an order and a Shippit invoice - will almost always be null on order creation.

courier_delivery_instructions
string

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 will contain the actual delivery instructions that get sent through the courier API when booked.

price
any

The price that will be charged for the allocated order.

If you're creating orders by passing in courier_type, the courier will usually not be yet be assigned at order creation and you will get 0. Courier allocation will be 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

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

The courier allocated to the order. See the ORDER CREATE courier_allocation API for available keywords.

tracking_histories
Array of objects (OrderResponseTrackingHistory)

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

The state of the order as progressed by the merchant.

object (Root Type for UserAttributes)

Represents the customers details attached to the order.

email
required
string

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
required
string

the customer's first name. If last_name is not provided, then it is used as the customer's full name.

last_name
string

customer's last name

mobile
string

Mobile number of the user / receiver.

required
object (OrderResponseOrderDocumentsHash)

A keyword hash of documents generated for an order. Usually populated during the LABEL call.

object (Root Type for LabelDocument)

A Label or document in the Labels API, representing a printable document available on a public URL.

url
string

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
file_type
string

File type of the label

encoded_label
string

If you have ZPL for your account, printable ZPL data for the document.

object (Root Type for LabelDocument)

A Label or document in the Labels API, representing a printable document available on a public URL.

url
string

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
file_type
string

File type of the label

encoded_label
string

If you have ZPL for your account, printable ZPL data for the document.

object (Root Type for LabelDocument)

A Label or document in the Labels API, representing a printable document available on a public URL.

url
string

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
file_type
string

File type of the label

encoded_label
string

If you have ZPL for your account, printable ZPL data for the document.

object (Root Type for LabelDocument)

A Label or document in the Labels API, representing a printable document available on a public URL.

url
string

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
file_type
string

File type of the label

encoded_label
string

If you have ZPL for your account, printable ZPL data for the document.

object (Root Type for LabelDocument)

A Label or document in the Labels API, representing a printable document available on a public URL.

url
string

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
file_type
string

File type of the label

encoded_label
string

If you have ZPL for your account, printable ZPL data for the document.

courier_job_id
string

The ID assigned by some carriers to the shipment/consignment.

qualified_url
required
string

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 this label after expiration, please make another request for a new URL to be issued.

Response samples

Content type
application/json
{}

Document

Book Document

Get Manifest Document from the courier

path Parameters
manifest_id
required
string

The id of the Manifest returned from book call.

Responses

Response Schema: application/json
object
manifest
string
manifest_id
integer <int32>
courier
string
manifest_pdf
string
order_count
integer <int32>
orders
Array of strings
success
boolean

Response samples

Content type
application/json
{}