Guides
/
Shipping
/
Batch Labels
Last updated

Batch Labels

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

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. If the shipments included in the batch do not explicitly specify their carrier and service, you'll recieve an error.

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.

Create a Batch

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 batch
  • batch_notes: A custom message for a particular batch
  • shipment_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)

Sample Request & Response

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"
}

Add to a Batch

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_id you wish to add shipments to.
  • The shipment_ids and/or rate_ids you wish to add to the batch.

Sample Request

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.

Update a Batch

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_id you wish update.
  • The shipment_ids and/or rate_ids you wish to add to the batch.

Sample Request

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.

Remove from a Batch

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_id of the batch with the shipment you want to remove.
  • The shipment_ids and/or rate_ids you wish to remove from the batch.

Sample Request

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

Process a Batch

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_id for the batch you wish to process.

Specifying a Label Format & Layout

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.

Sample Request

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"
}

Archive a Batch

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.

Sample Request

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.

Previous page
Next page