Create Batch

Batches allow you to process hundreds or thousands of labels at a time and receive the labels and any related documentation, like customs forms, in a single bulk response.

If you are new to batches in ShipEngine, be sure to read the Label Batches overview first.

To use batches successfully, you should also understand how to create a shipment, how to get shipping rates, and the basics around carrier services.

Requirements

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

Request Body

In the request body, you'll can the following (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 messages 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)

Example Request & Response

POST /v1/batches/

1
2
3
4
5
6
7
8
9
10
11
12
13
POST /v1/batches HTTP/1.1
Host: api.shipengine.com
API-Key: __YOUR_API_KEY_HERE__
Content-Type: application/json
{
  "external_batch_id": "1daa0c22-0519-46d0-8653-9f3dc62e7d2c",
  "batch_notes": "2019-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.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
{
  "label_layout": null,
  "label_format": null,
  "batch_id": "se-1013790",
  "external_batch_id": "1daa0c22-0519-46d0-8653-9f3dc62e7d2c",
  "batch_notes": "2019-7-25 Morning Shipments",
  "created_at": "2019-07-25T15:24:46.657Z",
  "errors": 0,
  "warnings": 0,
  "completed": 0,
  "forms": 0,
  "count": 1,
  "batch_shipments_url": {
    "href": "https://api.shipengine.com/v1/shipments?batch_id=se-1013790"
  },
  "batch_labels_url": {
    "href": "https://api.shipengine.com/v1/labels?batch_id=se-1013790"
  },
  "batch_errors_url": {
    "href": "https://api.shipengine.com/v1/batches/se-1013790/errors"
  },
  "label_download": {
    "href": "https://api.shipengine.com/v1/downloads/1/uths7PctKUqbM4OfmgzXLg/label-1013790.pdf"
  },
  "form_download": {
    "href": "https://api.shipengine.com/v1/downloads/1/xKVZeKA650-bvQB_oriYkQ/form-1013790.pdf"
  },
  "status": "open"
}