🎉ShipEngine is becoming ShipStation API🎉

Over the next few months you'll notice the ShipEngine website, documentation portal, and dashboard being rebranded as ShipStation API. For our ShipEngine customers, you don't need to take any action or change any of your integrations in any way. All endpoints will remain the same and continue to function as they always have.

To learn more about what's coming, review our New ShipStation API page.

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 ShipStation API, 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.

TIP:

Use Webhooks

Setting up webhooks will improve your batch experience since a webhook will be called when a batch is completed.

Requirements

• The batch_id for the batch you wish to process.
• All shipments in a batch, whether added with shipment_id or rate_id must have a carrier_id and service_code. If the shipments included in the batch do not explicitly specify their carrier and service, you'll recieve an error.
• All shipments in a batch must be shipped from the same warehouse. This means all shipments in a batch must be assigned the same warehouse_id.

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.

POST /v1/batches/se-1010644/process/labels HTTP/1.1

{
  "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.

1. List the batch errors to extract the shipments and the reasons why they failed.
2. Correct the errors in the shipments by updating the shipment.
3. Create a new batch for the shipments and rates in the invalid or error state.
4. Process the new batch.