List Batches

Once you have processed a batch you’ll want to get the batch details, which will include batch status, a list of errors (if any), and linke to download the resources.

You can get batch details in the following ways:

List batches: Get a list of batches that match your query parameters.
Get batch by id: Get the details of a specific batch with its batch_id.
Get batch by external batch id: Get the details of a specific batch with its external_batch_id.

List by Query Parameters

The GET /v2/batches method will return a response with an array of batches that meet your request parameters. Each batch in the response array will include batch properties like status, errors, and URLs to download the resources associated with the batch (labels, forms, etc).

Since there's potential for the response to include a large number of batches, you can filter the results with query parameters.

Query Parameter	Type	Description
`status`	enumerated string	`open`, `queued`, `completed`, `processing`, `archived`, `invalid`, `completed_with_errors`
`page`	integer	defaults to 1
`page_size`	integer	defaults to 100
`sort_dir`	string	`asc` or `desc`
`sort_by`	string	`ship_date`, `processed_at`

Sample Request & Response

GET /v2/batches

GET /v2/batches?status=open HTTP/1.1
Host: api.shipstation.com
API-Key: __YOUR_API_KEY_HERE__

Response

{
 "batches": [
   {
     "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"
   }
 ],
 "total": 1,
 "page": 1,
 "pages": 1,
 "links": {
   "first": {
     "href": "https://api.shipstation.com/v2/batches?status=open&page=1&page_size=100"
   },
   "last": {
     "href": "https://api.shipstation.com/v2/batches?status=open&page=1&page_size=100"
   },
   "prev": {},
   "next": {}
 }
}

Get Batch By ID

Use this method to get the batch details of a specific batch_id.

Requirements

The batch_id for the batch you wish to get.

Sample Request & Response

GET /v2/batches/:batch_id

GET /v2/batches/se-1013790 HTTP/1.1
Host: api.shipstation.com
API-Key: __YOUR_API_KEY_HERE__

Response

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

Get Batch By External Batch ID

This method allows you to retrieve batch resources via the external_batch_id value if you provided one when creating the batch.

Requirements

The external_batch_id for the batch you wish to get.

Sample Request & Response

GET /v2/batches/external_batch_id/:external_batch_id

GET /v2/batches/external_batch_id/32cc2f34-5d9e-466c-8e3f-62c38ad9dc46 HTTP/1.1
Host: api.shipstation.com
API-Key: __YOUR_API_KEY_HERE__

Response

The response for this call will have the same result as the get batch by id request.

{
 "label_layout": null,
 "label_format": null,
 "batch_id": "se-1013790",
 "external_batch_id": "32cc2f34-5d9e-466c-8e3f-62c38ad9dc46",
 "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"
}

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

List the batch errors to extract the shipments and the reasons why they failed.
Correct the errors in the shipments by updating the shipment.
Create a new batch for the shipments and rates in the invalid or error state.
Process the new batch.

List Batch Errors

If any of your batches encounter an error when processing, you can use the List Batch Errors call to specifically list the errors that occurred on the batch.

Example Request & Response

GET /v2/batches/:batch_id/errors

GET /v2/batches/se-12345/errors HTTP/1.1
Host: api.shipstation.com
API-Key: __YOUR_API_KEY_HERE__

Response

{
     "error": "Insufficient account balance",
     "shipment_id": "se-12345",
     "external_shipment_id": "TestId-1"
}