batches

List batches

Changed on Oct 22, 2026

List Batches associated with your Shipengine account

get/v1/batches

Request

Base URL: https://api.shipengine.com
URL: https://api.shipengine.com/v1/batches
Auth: API key in header API-Key

Query parameters

The possible batch status values

pageinteger

Return a specific page of results. Defaults to the first page. If set to a number that's greater than the number of pages of results, an empty page is returned.

page_sizeinteger

The number of results to return per response.

sort_dir'asc' | 'desc'

Controls the sort order of queries

Value	Description
asc	Return results in ascending order
desc	Return results in descending order

Controls the sort order of the query.

batch_numberstring

Batch Number

created_at_startstring date-time

Only return batches that were created on or after a specific date/time

created_at_endstring date-time

Only return batches that were created on or before a specific date/time

processed_at_startstring date-time

Only return batches that were processed on or after a specific date/time

processed_at_endstring date-time

Only return batches that were processed on or before a specific date/time

sort_by'ship_date' | 'processed_at' | 'created_at'

The possible batches sort by values

Response

The request was a success.

totalinteger required

The total number of batches the API call returned

pageinteger required

The page that is currently being read

pagesinteger required

The total number of batch pages the API call returned

Example response

{
  "batches": [
    {
      "batch_id": "se-28529731",
      "batch_notes": "Batch for morning shipment",
      "assigned_user": "a2df9fa5-b7ee-467f-be4e-9c660542c187",
      "created_at": "2018-09-23T15:00:00.000Z",
      "processed_at": "2018-09-23T15:00:00.000Z",
      "errors": 2,
      "process_errors": [
        {
          "error_source": "shipengine",
          "error_type": "validation",
          "error_code": "invalid_field_value",
          "message": "Body of request cannot be null.",
          "carrier_id": "se-28529731",
          "carrier_code": "dhl_express",
          "field_name": "shipment.ship_to.phone_number"
        }
      ],
      "warnings": 1,
      "completed": 1,
      "forms": 3,
      "count": 2,
      "batch_shipments_url": {
        "href": "https://example.com/resource"
      },
      "batch_labels_url": {
        "href": "https://example.com/resource"
      },
      "batch_errors_url": {
        "href": "https://example.com/resource"
      },
      "label_download": {
        "href": "https://example.com/resource",
        "pdf": "https://example.com/resource",
        "png": "https://example.com/resource",
        "zpl": "https://example.com/resource"
      },
      "packing_slip_download": {
        "href": "https://example.com/resource"
      },
      "form_download": {
        "href": "https://example.com/resource"
      },
      "paperless_download": {
        "href": "https://example.com/resource"
      }
    }
  ],
  "total": 10,
  "page": 1,
  "pages": 10,
  "links": {
    "first": {
      "href": "https://example.com/resource"
    },
    "last": {
      "href": "https://example.com/resource"
    },
    "prev": {
      "href": "https://example.com/resource"
    },
    "next": {
      "href": "https://example.com/resource"
    }
  }
}

Changes

Oct 22, 2026e998dffc42be Revision changes
- warning
  added the new bring_your_own_label_not_supported enum value to the ///// response property for the response status
- warning
  added the new bring_your_own_label_not_supported enum value to the // response property for the response status
- warning
  added the new bring_your_own_label_not_supported enum value to the // response property for the response status
- warning
  added the new multiple_sales_orders enum value to the ///// response property for the response status
- warning
  added the new multiple_sales_orders enum value to the // response property for the response status
- warning
  added the new multiple_sales_orders enum value to the // response property for the response status
- warning
  added the new sales_order_link_required enum value to the ///// response property for the response status
- warning
  added the new sales_order_link_required enum value to the // response property for the response status
- warning
  added the new sales_order_link_required enum value to the // response property for the response status
Oct 9, 2026020f57d6f5b8 Revision changes
- breaking
  the //// response's property type changed from no type to object for status
- breaking
  the / response's property type changed from no type to object for status
- breaking
  the / response's property type changed from no type to object for status
- info
  added the optional property ///// to the response with the status
- info
  added the optional property ///// to the response with the status
- info
  added the optional property ///// to the response with the status
- info
  added the optional property // to the response with the status
- info
  added the optional property // to the response with the status
- info
  added the optional property // to the response with the status
- info
  added the optional property // to the response with the status
- info
  added the optional property // to the response with the status
- info
  added the optional property // to the response with the status
- info
  removed from the //// response property allOf list for the response status
- info
  removed from the / response property allOf list for the response status
- info
  removed from the / response property allOf list for the response status
- info
  added the required property ///// to the response with the status
- info
  added the required property ///// to the response with the status
- info
  added the required property ///// to the response with the status
- info
  added the required property ///// to the response with the status
- info
  added the required property // to the response with the status
- info
  added the required property // to the response with the status
- info
  added the required property // to the response with the status
- info
  added the required property // to the response with the status
- info
  added the required property // to the response with the status
- info
  added the required property // to the response with the status
- info
  added the required property // to the response with the status
- info
  added the required property // to the response with the status

Operation history (6 revisions)