Process Batch

Processing a batch means you'll be creating and purchasing the labels for the shipments included in that batch. Once processed, you can then get the batch details by batch ID to download the batch labels and forms as well as check that batch status and the review any errors that may have occurred.

If you are new to batches in ShipEngine, be sure to read the Label Batches overview first.

To use batches successfully, you should also understand how to create a shipment, how to get shipping rates, and the basics around carrier services.

Requirements

Specifying a Label Format & Layout

You may optionally specify a format and layout for all the labels created with a batch. Unless otherwise specified, labels will be generated as 4x6 PDFs.

Example Request

POST /v1/batches/:batch_id/process/labels

In this example request, we specify label layout, format, and ship_date.

Copy

HTTPcURLJavaScriptNodeJSPHPPythonRubyC#JavaGoSwiftObjective-CPowerShell

1
2
3
4
5
6
7
8
9
10
POST /v1/batches/se-1010644/process/labels HTTP/1.1
Host: api.shipengine.com
API-Key: __YOUR_API_KEY_HERE__
Content-Type: application/json
{
  "ship_date": "2019-07-25T05:00:00.000Z",
  "label_layout": "4x6",
  "label_format": "pdf"
}

Error Handling

Errors in batches must be handled differently from synchronous requests. You must retrieve the status of your batch by getting a batch and getting an overview of the statuses, or by listing the batch errors.

Invalid or Completed with Errors

If the batch enters an Invalid or Completed with Errors state, you cannot re-use the batch.