Book API

The Book API initiates a booking with the carriers for orders you have already labelled. It takes an array of orders and books each one with its allocated carrier, then returns a manifest per carrier.

Endpoints

POST/bookBook labelled orders with their carriers
GET/book/{manifest_id}/documentRetrieve the manifest document for a booking

The booking object

A booking can fail per carrier rather than outright, so response carries a success flag and its own error fields for each manifest.

responsearray of objectsOptional

Array of booking statuses at each courier

Show child attributesHide child attributes

courierstringOptional: The human-readable name of the courier where the booking was made.
courier_allocationstringOptional: The class-level identifier for the courier. Corresponds to the courier_allocation value used when creating the order.
manifeststringOptional: The Manifest ID of the booking
manifest_pdfstringOptional: 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_countinteger(int32)Optional: How many orders were included in this manifest.
successbooleanOptional: Whether or not the booking succeeded
ordersstringOptional: An array of order tracking numbers included in this status. Used to indicate which orders failed to manifest in the case where success = false.
errorstringOptional: Error code that applies to the individual bookings / orders referenced.
error_descriptionstringOptional: Human-readable error message applied to the individual bookings / orders referenced.

errorstringOptional

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 is successful and individual errors are applied in the body of each booked item.

error_descriptionstringOptional

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

countintegerOptional

Number of items in the response

Sample responseJSON

{
  "response": [
    {
      "courier": "eParcel Express",
      "courier_allocation": "EparcelExpress",
      "manifest": "ABC0000214",
      "manifest_pdf": "https://shippit.com/manifest20160721-96368-1tpowvr.pdf",
      "order_count": 2,
      "success": true
    },
    {
      "courier": "Fastway",
      "courier_allocation": "Fastway",
      "manifest": "FW20160721215",
      "manifest_pdf": "https://shippit.com/manifest20160721-96368-1tpowvr.pdf",
      "order_count": 2,
      "success": true
    },
    {
      "courier": "Couriers Please",
      "courier_allocation": "CouriersPlease",
      "manifest": "JJJ20160721216",
      "manifest_pdf": "https://shippit.com/manifest20160721-96368-1tpowvr.pdf",
      "order_count": 4,
      "success": true
    },
    {
      "courier": "eParcel",
      "courier_allocation": "Eparcel",
      "manifest": "ABC0000217",
      "manifest_pdf": "https://shippit.com/manifest20160721-96368-1tpowvr.pdf",
      "order_count": 2,
      "success": true
    }
  ],
  "count": 4
}

Book orders

POST/book

Given an array of orders, this initiates a booking with their respective couriers. Orders must be labelled first before they can be booked. A maximum of 1000 orders can be booked at a time.

To perform this operation, you must be authenticated with an authentication token.

This API validates that all of the requested orders are accurate and ready for booking, if all of the orders sent in can't be booked, the response details which orders aren't found. This response means that none of the order numbers sent in have been booked. If a manifest can't be generated, the response includes an array of orders on each manifest which have not been booked.

Parameters

ordersstringRequired: An array of Shippit tracking numbers, corresponding to the orders which you would like to book. Must be fewer than 1000 tracking numbers.

Response codes

Status	Meaning	Description
200	OK	Returns the status of the bookings at each courier.
400	Bad Request	Returned when Shippit has a problem with the input parameters. Not all input errors can result in this error. Depending on the request, errors are sometimes parsed as an unknown error or as part of the response body. If returned as text/html, it's blank.
403	Forbidden	Returned when the API key doesn't match a valid merchant account, or the API secret is missing the permission this endpoint requires.
422	Unprocessable Entity	Returned when the request contains more than 1000 tracking numbers.
500	Internal Server Error	Returned when an unknown error occurs. May be returned if Shippit has trouble with the combination of the input or merchant account configuration.

RequestJSON

{
  "orders": [
    "PPKNpNhR0A5Ud",
    "PP2ZlACi2vtxNY",
    "PPKNpNhR0A5Ud"
  ]
}

Response

JSON

{
  "response": [
    {
      "error": "orders_not_available_to_book",
      "error_description": "The requested orders could not be found. Please remove and try again.",
      "orders": [
        "invalid-tracking"
      ],
      "success": false
    }
  ],
  "count": 1
}

JSON

{
  "response": [
    {
      "courier": "Fastway",
      "error": "Manifest creation failed",
      "manifest": "FW20160721224",
      "orders": [
        "ppd5q24mtuett"
      ],
      "success": false
    },
    {
      "courier": "Couriers Please",
      "error": "Manifest creation failed",
      "manifest": "JJJ20160721225",
      "orders": [
        "pp0myuwhnajn4"
      ],
      "success": false
    }
  ],
  "count": 2
}

Retrieve a manifest document

GET/book/{manifest_id}/document

Get a manifest document from the courier.

To perform this operation, you must be authenticated with an authentication token.

Parameters

manifest_idstringpathRequired: The id of the Manifest returned from book call.

The manifest document object

responseobjectOptional: none
manifeststringOptional: none
manifest_idinteger(int32)Optional: none
courierstringOptional: none
manifest_pdfstringOptional: none
order_countinteger(int32)Optional: none
ordersstringOptional: none
successbooleanOptional: none

Response codes

Status	Meaning	Description
200	OK	Success response
403	Forbidden	Returned when the API key doesn't match a valid merchant account, when the API secret lacks the permission this endpoint requires, or when the manifest belongs to another account.
404	Not Found	Returned when the manifest ID doesn't match a manifest in Shippit.
422	Unprocessable Entity	Returned when the manifest hasn't finished generating. Try again shortly.
424	Failed Dependency	Returned when the manifest failed to book with the carrier.
500	Internal Server Error	Returned when an unknown error occurs. May be returned if Shippit has trouble with the combination of the input or merchant account configuration.

Response

JSON

{
    "response": {
        "manifest": "SHP934006_1771375849",
        "manifest_id": 934006,
        "courier": "Allied Express",
        "manifest_pdf": "https://shippit.s3.ap-southeast-2.amazonaws.com/uploads/order_manifest/attachment/934006/manifest20260218-1608-jxz3t0.pdf?X-Amz-Expires=561600&X-Amz-Date=20260218T00512Z&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIA54OGRPIRHSB2E3N7%2F20260218%2Fap-southeast-2%2Fs3%2Faws4_request&X-Amz-SignedHeaders=host&X-Amz-Signature=9eb6cf1843c166d18b3d2ad08f45cd3d4484ed09b8eb9323db53d4a6def04af",
        "order_count": 1,
        "orders": [
            "ppgiwawcoygj9"
        ],
        "success": true
    }
}