---
title: "Get Batch By ID"
method: GET
path: "/v1/batches/{batch_id}"
tags: ["batches"]
---

# Get Batch By ID

`GET /v1/batches/{batch_id}`

Get Batch By ID

## Response `200`

The request was a success.

- GetBatchByIdResponseBody — Batches are an advanced feature of ShipEngine designed for users who need to generate hundreds or thousands of labels at a time.
  - `label_layout` '4x6' | 'letter' | 'A4' | 'A6', required — The available layouts (sizes) in which shipping labels can be downloaded. The label format determines which sizes are supported. `4x6` is supported for all label formats, whereas `letter` (8.5" x 11") is only supported for `pdf` format.
  - `label_format` 'pdf' | 'png' | 'zpl', required — The possible file formats in which shipping labels can be downloaded. We recommend `pdf` format because it is supported by all carriers, whereas some carriers do not support the `png` or `zpl` formats. |Label Format | Supported Carriers |--------------|----------------------------------- |`pdf` | All carriers |`png` | `fedex` <br> `stamps_com` <br> `ups` <br> `usps` |`zpl` | `access_worldwide` <br> `apc` <br> `asendia` <br> `dhl_global_mail` <br> `dhl_express` <br> `dhl_express_australia` <br> `dhl_express_canada` <br> `dhl_express_worldwide` <br> `dhl_express_uk` <br> `dpd` <br> `endicia` <br> `fedex` <br> `fedex_uk` <br> `firstmile` <br> `imex` <br> `newgistics` <br> `ontrac` <br> `rr_donnelley` <br> `stamps_com` <br> `ups` <br> `usps`
  - `batch_id` string, required — A string that uniquely identifies a ShipEngine resource, such as a carrier, label, shipment, etc.
  - `batch_number` string, required — The batch number.
  - `external_batch_id` string, nullable, required — A string that uniquely identifies the external batch
  - `batch_notes` string, nullable, required — Custom notes you can add for each created batch
  - `created_at` string, date-time, required — An [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) string that represents a date and time.
  - `processed_at` string, date-time, required — An [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) string that represents a date and time.
  - `errors` integer, required — The number of errors that occurred while generating the batch
  - `process_errors` Error[], required — The errors associated with the failed API call
    - `error_source` 'carrier' | 'order_source' | 'shipengine', required — The source of the error, as indicated by the name this informs us if the API call failed because of the carrier, the order source, or the ShipEngine API itself.
    - `error_type` 'account_status' | 'business_rules' | 'validation' | 'security' | 'system' | 'integrations', required — The type of error
    - `error_code` 'auto_fund_not_supported' | 'batch_cannot_be_modified' | 'carrier_conflict' | 'carrier_disconnected' | 'carrier_not_connected' | 'carrier_not_supported' | 'confirmation_not_supported' | 'default_warehouse_cannot_be_deleted' | 'field_conflict' | 'field_value_required' | 'forbidden' | 'identifier_conflict' | 'identifiers_must_match' | 'insufficient_funds' | 'invalid_address' | 'invalid_billing_plan' | 'invalid_field_value' | 'invalid_identifier' | 'invalid_status' | 'invalid_string_length' | 'label_images_not_supported' | 'meter_failure' | 'order_source_not_active' | 'rate_limit_exceeded' | 'refresh_not_supported' | 'request_body_required' | 'return_label_not_supported' | 'settings_not_supported' | 'subscription_inactive' | 'terms_not_accepted' | 'tracking_not_supported' | 'trial_expired' | 'unauthorized' | 'unknown' | 'unspecified' | 'verification_failure' | 'warehouse_conflict' | 'webhook_event_type_conflict' | 'customs_items_required' | 'incompatible_paired_labels' | 'invalid_charge_event' | 'invalid_object' | 'no_rates_returned' | 'file_not_found' | 'shipping_rule_not_found' | 'service_not_determined' | 'no_rates_returned' | 'funding_source_registration_in_progress' | 'insurance_failure' | 'funding_source_missing_configuration' | 'funding_source_error', required — The error code specified for the failed API Call
    - `message` string, required — An error message associated with the failed API call
    - `carrier_id` string — A string that uniquely identifies a ShipEngine resource, such as a carrier, label, shipment, etc.
    - `carrier_code` string — A [shipping carrier](https://www.shipengine.com/docs/carriers/setup/), such as `fedex`, `dhl_express`, `stamps_com`, etc.
    - `field_name` string — The name of the field that caused the error
  - `warnings` integer, required — The number of warnings that occurred while generating the batch
  - `completed` integer, required — The number of labels generated in the batch
  - `forms` integer, required — The number of forms for customs that are available for download
  - `count` integer, required — The total of errors, warnings, and completed properties
  - `batch_shipments_url` OptionalLink, required — A link to a related resource, or an empty object if there is no resource to link to
    - `href` string, url — A URL
    - `type` string — The type of resource, or the type of relationship to the parent resource
  - `batch_labels_url` OptionalLink, required — A link to a related resource, or an empty object if there is no resource to link to
    - `href` string, url — A URL
    - `type` string — The type of resource, or the type of relationship to the parent resource
  - `batch_errors_url` OptionalLink, required — A link to a related resource, or an empty object if there is no resource to link to
    - `href` string, url — A URL
    - `type` string — The type of resource, or the type of relationship to the parent resource
  - `label_download` LabelDownload, required — Reference to the various downloadable file formats for the generated label
    - `href` string, url — A URL
    - `pdf` string, url — A URL
    - `png` string, url — A URL
    - `zpl` string, url — A URL
  - `form_download` OptionalLink, required — A link to a related resource, or an empty object if there is no resource to link to
    - `href` string, url — A URL
    - `type` string — The type of resource, or the type of relationship to the parent resource
  - `paperless_download` PaperlessDownload, required — The paperless details which may contain elements like `href`, `instructions` and `handoff_code`.
    - `href` string, url — A URL
    - `instructions` string, nullable — The instructions for the paperless download.
    - `handoff_code` string, nullable — The handoff code for the paperless download.
  - `status` 'open' | 'queued' | 'processing' | 'completed' | 'completed_with_errors' | 'archived' | 'notifying' | 'invalid', required — The possible batch status values

## Other responses

- `400` — The request contained errors.
- `404` — The specified resource does not exist.
- `500` — An error occurred on ShipEngine's side. > This error will automatically be reported to our engineers.

---

[API](https://skmtc.net/shipengine/apis/shipengine-api.md) · [All operations](https://skmtc.net/shipengine/apis/shipengine-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/shipengine/shipengine-api/revisions/6af91511d87e/schema)