Process a Batch

tip

Requirements

Please make sure you read the Using Batches documentation first.

Batch creating labels, requires that you have created a batch and added labels or rates to a batch.

Setting Up Web Hooks will also improve the experience while using batches, since a web hook will be called when a batch is completed.

Depending on how many labels you need to create, you can save a lot of time by using batch label creation. Additionally, you can create multiple batches and request that they be processed at a later time.

Example

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

Info

Specifying a Label Format and Layout

You may optionally specify a format and layout for all the labels created with a batch. By default, labels will be generated as 4x6 PDFs. Please see Label Size & Label Format for supported formats.

curl -iX POST https://api.shipengine.com/v1/batches/se-1010644/process/labels \
-H 'API-Key: __YOUR_API_KEY_HERE__' \
-d '
{
  "ship_date": "2019-07-25T05:00:00.000Z",
  "label_layout": "4x6",
  "label_format": "pdf"
}'
  • curl

If successful, responds with HTTP Status 204, No Content. Otherwise, you will receive a message back from the server with the error.

Warning

Invalid or Completed with Errors

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

  1. Use List 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 shipments and rates in an invalid or error state.
  4. Re-process the batch as a new batch.