Shippit (3.0)

Download OpenAPI specification:Download

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

Authentication

AuthToken

To make requests to the API, an authentication token is required. This can be passed by including the auth_token query parameter on all API requests.

To view your API key, login to your Shippit account, then visit Settings -> Integrations. You should see the token labelled as API Key.

Rate Limiting

All our APIs are rate limited to 60 requests per rolling 60 seconds per merchant (based on your auth_token). If you exceed this rate you'll receive a 429 HTTP error

Should you need a higher rate, please contact our support.

Security scheme type: API Key
query parameter name: auth_token

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.

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_qutotes 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:
Request Body schema: application/json
quote
required
object (Root Type for quote)

A specification of the queries to include in the quote.

Responses

200

Successful quote response

Response Schema: application/json
count
number

Number of quote results returned.

error
string

Error code returned by shippit.

error_description
string

Human-readable description of error encountered.

response
Array of object (Root Type for Quote)

The Quote returned by the carrier

post /quotes

Shippit API Production

https://www.shippit.com/api/3/quotes

Shippit API Staging

https://staging.shippit.com/api/3/quotes

Request samples

application/json
Copy
Expand all Collapse all
{
  • "quote":
    {
    }
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "response":
    [
    ],
  • "count": 3
}

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, etc.


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.

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.

Authorizations:
Request Body schema: application/json

Passes an Order object under the order field.

order
required
object (Root Type for Order)

Represents an Order to be delivered by Shippit.

Responses

200

Successful order response

Response Schema: application/json
error
string

Error code returned by shippit

error_description
string

Human-readable description of error encountered.

response
object (Root Type for Order)

Represents an Order to be delivered by Shippit.

post /orders

Shippit API Production

https://www.shippit.com/api/3/orders

Shippit API Staging

https://staging.shippit.com/api/3/orders

Request samples

application/json
Copy
Expand all Collapse all
{
  • "order":
    {
    }
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "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.

path Parameters
tracking_number
required
string

The tracking number of the Order.

Responses

200

Returns the Order with state = cancelled

Response Schema: application/json
error
string

Error code returned by shippit

error_description
string

Human-readable description of error encountered.

response
object (Root Type for Order)

Represents an Order to be delivered by Shippit.

422

Returns an error indicating that the Order could not be cancelled, and stating the reason why.

delete /orders/{tracking_number}

Shippit API Production

https://www.shippit.com/api/3/orders/{tracking_number}

Shippit API Staging

https://staging.shippit.com/api/3/orders/{tracking_number}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "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:
path Parameters
tracking_number
required
string

The tracking number of the Order.

Responses

200

Returns an Order and related label information.

Response Schema: application/json
error
string

Error code returned by Shippit

error_description
string

Human-readable description of error encountered

response
object (Root Type for Label)

Represents an Order and related labelling information

404

Returns an error indicating that the Order could not be found in Shippit

422

Returns an error indicating that the Order cannot yet be processed for labelling.

Typically this is because the Order has yet to be processed or allocatated a courier.

get /orders/{tracking_number}/label

Shippit API Production

https://www.shippit.com/api/3/orders/{tracking_number}/label

Shippit API Staging

https://staging.shippit.com/api/3/orders/{tracking_number}/label

Response samples

application/json
Copy
Expand all Collapse all
{