When using the batches endpoint, you can process labels in bulk and receive a large number of labels and customs forms in bulk responses. Batching is ideal for workflows that need to process hundreds or thousands of labels quickly.
Some common use cases for batching labels include:
- Printing bulk labels and customs forms: Essentially, it's easier and faster to send a single document with 100 "labels" to a label printer than it is to send 100 documents with one label each.
- 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).
- The shipments you add to a batch must use a
warehouse_idinstead of theship_fromaddress. - All shipments in a batch must be assigned the same
warehouse_id. - All shipments in a batch, whether added with
shipment_idorrate_idmust have acarrier_idandservice_code. If the shipments included in the batch do not explicitly specify their carrier and service, you'll recieve an error.
The basic lifecylce of a batch includes these four tasks:
- Create a batch
- Add shipment_ids and/or rate_ids to the batch
- Process the batch
- Get batch details including batch status, list of errors (if any), and download the resources.
When creating a batch, you can include the following in the request body (though none of these properties are required when creating the batch):
external_batch_id: A string that uniquely identifies the external batchbatch_notes: A custom message for a particular batchshipment_ids: Array of shipment IDs used in the batch (you can also add shipments to the batch later)rate_ids: Array of rate IDs used in the batch (you can also add rates to the batch later)
POST /v2/batches/
POST /v2/batches HTTP/1.1
Host: api.shipstation.com
API-Key: __YOUR_API_KEY_HERE__
Content-Type: application/json
{
"external_batch_id": "1daa0c22-0519-46d0-8653-9f3dc62e7d2c",
"batch_notes": "2024-7-25 Morning Shipments",
"shipment_ids": [
"se-2102769"
],
"rate_ids": []
}Response
The response will return the new batch properties, including the batch_id you'll need for adding shipments to the batch and processing the batch.
{
"label_layout": null,
"label_format": null,
"batch_id": "se-1013790",
"external_batch_id": "1daa0c22-0519-46d0-8653-9f3dc62e7d2c",
"batch_notes": "2024-7-25 Morning Shipments",
"created_at": "2024-07-25T15:24:46.657Z",
"errors": 0,
"warnings": 0,
"completed": 0,
"forms": 0,
"count": 1,
"batch_shipments_url": {
"href": "https://api.shipstation.com/v2/shipments?batch_id=se-1013790"
},
"batch_labels_url": {
"href": "https://api.shipstation.com/v2/labels?batch_id=se-1013790"
},
"batch_errors_url": {
"href": "https://api.shipstation.com/v2/batches/se-1013790/errors"
},
"label_download": {
"href": "https://api.shipstation.com/v2/downloads/1/uths7PctKUqbM4OfmgzXLg/label-1013790.pdf"
},
"form_download": {
"href": "https://api.shipstation.com/v2/downloads/1/xKVZeKA650-bvQB_oriYkQ/form-1013790.pdf"
},
"status": "open"
}Once you've created a batch, you can continue to add shipment_ids and/or rate_ids to it until you are ready to process the batch.
In addition to the other batch requirements, you’ll need:
- The
batch_idyou wish to add shipments to. - The
shipment_idsand/orrate_idsyou wish to add to the batch.
POST /v2/batches/:batch_id/add
POST /v2/batches/se-1010644/add HTTP/1.1
Host: api.shipstation.com
API-Key: __YOUR_API_KEY_HERE__
Content-Type: application/json
{
"shipment_ids": [
"se-2102769"
],
"rate_ids": []
}If successful, ShipStation will respond with HTTP Status 204, No Content.
In addition to the add to batch option (which uses the POST method with the /v2/batches/:batch_id/add endpoint), you can update a batch to add shipment_ids and/or rate_ids to it. This option uses the PUT method with the /v2/batches/:batch_id endpoint.
In addition to the other batch requirements, you’ll need:
- The
batch_idyou wish update. - The
shipment_idsand/orrate_idsyou wish to add to the batch.
PUT /v2/batches/:batch_id
PUT /v2/batches/se-1010644 HTTP/1.1
Host: api.shipstation.com
API-Key: __YOUR_API_KEY_HERE__
Content-Type: application/json
{
"shipment_ids": [
"se-2102769"
],
"rate_ids": []
}If successful, ShipStation will respond with HTTP Status 204, No Content.
Should you need to remove any shipment_ids or rate_ids from a batch before processing the batch, you can do so.
In addition to the other batch requirements, you’ll need:
- The
batch_idof the batch with the shipment you want to remove. - The
shipment_idsand/orrate_idsyou wish to remove from the batch.
POST /v2/batches/:batch_id/remove
POST /v2/batches/se-1010644/remove HTTP/1.1
Host: api.shipstation.com
API-Key: __YOUR_API_KEY_HERE__
Content-Type: application/json
{
"shipment_ids": [
"se-2102769"
],
"rate_ids": []
}If successful, ShipStation will respond with HTTP Status 204, (No Content).
Processing a batch means you'll be creating and purchasing the labels for the shipments included in that batch. Once processed, you can then get the batch details by batch ID to download the batch labels and forms as well as check that batch status and the review any errors that may have occurred.
In addition to the other batch requirements, you’ll need:
- The
batch_idfor the batch you wish to process.
You may optionally specify a format and layout for all the labels created with a batch. Unless otherwise specified, labels will be generated as 4x6 PDFs.
POST /v2/batches/:batch_id/process/labels
In this example request, we specify label layout, format, and ship_date.
POST /v2/batches/se-1010644/process/labels HTTP/1.1
Host: api.shipstation.com
API-Key: __YOUR_API_KEY_HERE__
Content-Type: application/json
{
"ship_date": "2024-07-25T05:00:00.000Z",
"label_layout": "4x6",
"label_format": "pdf"
}You can archive your open batches, which is useful for organizing and filtering various batch statuses via a request with a status query, like GET /v1/batches?status=open.
DELETE /v2/batches/:batch_id
DELETE /v2/batches/se-1013826 HTTP/1.1
Host: api.shipstation.com
API-Key: __YOUR_API_KEY_HERE__When a batch has successfully been archived, you will receive a response with the HTTP Status 204, No Content status.