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.
- Be explicit when you create a shipment, and specify your
carrier_id
andservice_code
. - 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
andservice_code
or use arate_id
. - Setup webhooks to proactively fix errors as they surface.
Batch Lifecycle
- Create a Batch
- Add Shipments and/or Rates to a Batch
- Process the Batch
- 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
.