Bulk Label Downloads

What are Batches?

Batches are an advanced feature of ShipEngine designed for users who need to generate hundreds or thousands of labels at a time. When ShipEngine generates labels it relies on many carriers, their services, their dependencies, and a number of other variables to fulfill your requests; those requests can take a few minutes for us to get back to you.

We created a batching service so you can receive large amounts of labels and customs forms back in bulk responses.

Why use Batches?

A primary use-case behind batches is printing bulk labels and customs forms; it's easier to print to the label printer a single document with 100 "labels" than 100 documents with 1 "label".

Additionally, you may use batches for grouping shipments for processing internally at your warehouse for different locations, or different packing requirements. E.g. a morning pickup batch, a contains alcohol batch, etc.

Explicitness in Shipments

When you add to a batch you must be explicit with what you want.

  1. Be explicit when you create a shipment, and specify your carrier_id and service_code.
  2. Be explicit with rates when you add to a batch request by providing the rate_id you received when getting rates.

When you're explicit with your shipments, there will be less processing errors.

  • Validate your Addresses
  • Choose a rate selection strategy, either carrier_id and service_code or use a rate_id.
  • Setup web hooks to proactively fix errors as they surface.

Batch Lifecycle

  1. Create a Batch
  2. Add Shipments and/or Rates to a Batch
  3. Process the Batch
  4. Get the Status of a Batch, check for errors, download the resources.

Error Handling

Error handling 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.

Warnings and Requirements

  • The use of Warehouses is required.
  • All shipments in a batch must be assigned the same warehouse_id.


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