List Batches

The list batches call 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 (labes, forms, etc).

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

Query Parameter	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`	`asc` or `desc`
`sort_by`	`ship_date`, `processed_at`

Example Request & Response

GET /v1/batches

1
2
3
GET /v1/batches?status=open HTTP/1.1
Host: api.shipengine.com
API-Key: __YOUR_API_KEY_HERE__

Response

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
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
{
  "batches": [
    {
      "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"
    }
  ],
  "total": 1,
  "page": 1,
  "pages": 1,
  "links": {
    "first": {
      "href": "https://api.shipengine.com/v1/batches?status=open&page=1&page_size=100"
    },
    "last": {
      "href": "https://api.shipengine.com/v1/batches?status=open&page=1&page_size=100"
    },
    "prev": {},
    "next": {}
  }
}