# 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](#create-a-batch)
2. [Add shipment_ids and/or rate_ids to the batch](#add-to-a-batch)
3. [Process the batch](#process-a-batch)
4. [Get batch details](/list-batches) 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](#add-to-a-batch) later)
- `rate_ids`: Array of rate IDs used in the batch (you can also [add rates to the batch](#add-to-a-batch) later)


### Sample Request & Response

**POST /v2/batches/**


```http
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](#process-a-batch).


```json
{
 "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](#process-a-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**


```http
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**


```http
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**


```http
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](/list-batches) 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`.


```http
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**


```http
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.