Batch Book

Use this endpoint to book all quotes in a batch. Each quote is booked independently; failures are captured per-quote (partial success). Returns booking results for each quote and a combined PDF of all successfully generated shipping labels.

The batch must have status open to be booked. The batch status transitions to processing during booking, then to completed or failed when finished.

REST Endpoint

POST /restapi/v1/customers/:customerId/batch-book

Request Content Type

application/json

Request JSON Example

POST /restapi/v1/customers/TEST00002/batch-book

{
  "batchId": 42
}

Explanation of Request Fields

Field	JSON Type	Required	Description
batchId	integer	true	The batch ID to book. The batch must have status "open" and contain at least one quote.

Response Status Code

200 OK

Response Content Type

application/json

Response JSON Example

{
  "results": [
    {
      "quoteId": 1234,
      "status": "success",
      "bookNumber": "2456789",
      "trackingNumber": "1Z999AA10123456784",
      "lastMileTrackingNumber": "",
      "totalShippingCost": "16.27",
      "zone": "2"
    },
    {
      "quoteId": 1235,
      "status": "error",
      "error": "Insufficient prepay balance",
      "errorCategory": "INVALID_REQUEST"
    }
  ],
  "labelsPdf": "<base64-encoded-pdf>",
  "prepayBalance": "483.73"
}

Explanation of Response Fields

Field	Type	Description
results	array	One entry per quote in the batch
results[n].quoteId	integer	The quote ID
results[n].status	string	"success" or "error"
results[n].bookNumber	string	Book number assigned to the shipment (only present when status is "success")
results[n].trackingNumber	string	Carrier tracking number (only present when status is "success")
results[n].lastMileTrackingNumber	string	Last-mile tracking number, if applicable (only present when status is "success")
results[n].totalShippingCost	decimal	Total shipping cost charged (only present when status is "success")
results[n].zone	string	Zone used for the shipment (only present when status is "success")
results[n].error	string	Error message (only present when status is "error")
results[n].errorCategory	string	Error category code (only present when status is "error")
labelsPdf	string	Base64-encoded combined PDF of all successfully booked shipping labels. Empty string if no labels could be generated.
prepayBalance	decimal	Updated prepay balance after booking (only present when at least one shipment was booked)

Notes

• The batch must have status open. Batches with status processing, completed, failed, or cancelled cannot be booked.
• Each quote is booked independently. If one fails, the others will still be booked.
• After booking, the batch status is set to completed (at least one success) or failed (all failed). Use the Get Batch Errors endpoint to retrieve detailed error information.
• The labelsPdf field contains a single PDF document combining all successfully generated labels.
• Maximum of 500 quotes per batch.