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