shipengine-logo

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 webhooks 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]/reference/list-batch-errors).

Warnings and Requirements

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