Site Logo

🎉 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.

Label Batches

Batches are an advanced feature for generating hundreds or thousands of labels at a time. When ShipStation API generates labels, it relies on many carriers, their services, their dependencies, and multiple other variables to fulfill your requests. Combined, all of these requests can take a few minutes.

With our batch feature, you can process labels in bulk and receive a large number of labels and customs forms in bulk responses.

Common Use Cases

A primary use case for batching is printing bulk labels and customs forms. Essentially, it's easier send a single document with 100 "labels" to a label printer than it is to send 100 documents with one label each.

You can also use batches to group shipments for processing internally at your warehouse. For example, batch labels that ship from a specific warehouse or have specific packing or shipping requirements (like a morning pickup batch, a contains alcohol batch, etc).

Batch Lifecycle

The basic lifecylce of a batch includes these four tasks:

  1. Create a batch
  2. Add shipment_ids and/or rate_ids to the batch
  3. Process the batch
  4. Get batch details including batch status, list of errors (if any), and download the resources.

Requirements

  • The shipments you add to a batch must use a warehouse_id instead of the ship_from address.
  • All shipments in a batch must be assigned the same warehouse_id.
  • All shipments in a batch, whether added with shipment_id or rate_id must have a carrier_id and service_code.

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.