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 number for the booking, and the reference the carrier knows the manifest by. This is the same value the Order API returns as manifest_number. It isn't the value you pass to the book document endpoint.
manifest_idinteger(int32)Optional: The Shippit ID of the manifest. Pass this to the book document endpoint to fetch the manifest document. When success is false, Shippit discards the manifest, so the ID no longer resolves.
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. To access this document after the URL expires, request a new URL.
order_countinteger(int32)Optional: The number of orders 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_id": 934006,
      "manifest_pdf": "https://shippit.com/manifest20160721-96368-1tpowvr.pdf",
      "order_count": 2,
      "success": true
    },
    {
      "courier": "Fastway",
      "courier_allocation": "Fastway",
      "manifest": "FW20160721215",
      "manifest_id": 934007,
      "manifest_pdf": "https://shippit.com/manifest20160721-96368-1tpowvr.pdf",
      "order_count": 2,
      "success": true
    },
    {
      "courier": "Couriers Please",
      "courier_allocation": "CouriersPlease",
      "manifest": "JJJ20160721216",
      "manifest_id": 934008,
      "manifest_pdf": "https://shippit.com/manifest20160721-96368-1tpowvr.pdf",
      "order_count": 4,
      "success": true
    },
    {
      "courier": "eParcel",
      "courier_allocation": "Eparcel",
      "manifest": "ABC0000217",
      "manifest_id": 934009,
      "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",
      "manifest_id": 934010,
      "orders": [
        "ppd5q24mtuett"
      ],
      "success": false
    },
    {
      "courier": "Couriers Please",
      "error": "Manifest creation failed",
      "manifest": "JJJ20160721225",
      "manifest_id": 934011,
      "orders": [
        "pp0myuwhnajn4"
      ],
      "success": false
    }
  ],
  "count": 2
}

Retrieve a manifest document

GET/book/{manifest_id}/document

Get a manifest document from the courier.

The manifest_id in the path is the Shippit ID of the manifest, returned as manifest_id by the Book API and, for a booked order, by the Order API. It isn't the manifest number.

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

Parameters

manifest_idintegerpathRequired: The Shippit ID of the manifest, returned as manifest_id by the Book API or the Order API.

The manifest document object

responseobjectOptional: The manifest document.
manifeststringOptional: The manifest number for the booking, and the reference the carrier knows the manifest by. It isn't the value you pass in the path.
manifest_idinteger(int32)Optional: The Shippit ID of the manifest, matching the manifest_id in the path.
courierstringOptional: The human-readable name of the courier that holds the manifest.
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. To access this document after the URL expires, request a new URL.
order_countinteger(int32)Optional: The number of orders in this manifest.
ordersstringOptional: An array of order tracking numbers included in this manifest.
successbooleanOptional: Whether the booking succeeded.

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
    }
}