---
title: "Get batch by external id"
method: GET
path: "/v2/batches/external_batch_id/{external_batch_id}"
tags: ["batches"]
---

# Get batch by external id

`GET /v2/batches/external_batch_id/{external_batch_id}`

<aside class="access" aria-label="Endpoint access">
      <table class="access__table">
        <thead>
          <tr>
            <th class="access__table-header">Products</th>
            <th class="access__table-header">Plans</th>
          </tr>
        </thead>
        <tbody>
          <tr>
            <td class="access__table-cell access__product">
              <img class="access__logo" src="/static/logos/shipstation-api-logo.svg" alt="ShipStation API Logo" loading="lazy" decoding="async"/>
              <div class="access__sub">Formerly ShipEngine</div>
            </td>
            <td class="access__table-cell access__plans">
              <a href="/apis/@shipstation-v2/docs/getting-started/plans/shipstation-api-free.md" class="access__plan">Free</a>
              <a href="/apis/@shipstation-v2/docs/getting-started/plans/shipstation-api-advanced-enterprise.md" class="access__plan">Advanced</a>
              <a href="/apis/@shipstation-v2/docs/getting-started/plans/shipstation-api-advanced-enterprise.md" class="access__plan">Enterprise</a>
            </td>
          </tr>
          <tr>
            <td class="access__table-cell">
              <img class="access__logo" src="/static/logos/shipstation-logo.svg" alt="ShipStation Logo" loading="lazy" decoding="async"/>
            </td>
            <td class="access__table-cell access__plans">
              <a href="/apis/@shipstation-v2/docs/getting-started/plans/shipstation-free-starter.md" class="access__plan access__plan--off">Free</a>
              <a href="/apis/@shipstation-v2/docs/getting-started/plans/shipstation-free-starter.md" class="access__plan access__plan--off">Starter</a>
              <a href="/apis/@shipstation-v2/docs/getting-started/plans/shipstation-standard-premium.md" class="access__plan">Standard</a>
              <a href="/apis/@shipstation-v2/docs/getting-started/plans/shipstation-standard-premium.md" class="access__plan">Premium</a>
            </td>
          </tr>
        </tbody>
      </table>
      <footer class="access__footer">
        <a class="access__help" href="/apis/@shipstation-v2/docs/getting-started/products-and-plans.md">
          Learn about products and plans
          <img src="/static/icons/external-link.svg" alt="External Link Icon" style="width: 16px;" loading="lazy" decoding="async"/>
        </a>
      </footer>
    </aside>

Retreive a batch using an external batch ID

## Response `200`

The request was a success.

- GetBatchByExternalIdResponseBody — Batches are an advanced feature of ShipStation designed for users who need to generate hundreds or thousands of labels at a time.
  - `label_layout` '4x6' | 'letter', 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 ShipStation resource, such as a carrier, label, shipment, etc.
  - `batch_number` string, required — The batch number.
  - `external_batch_id` string, required — A string that uniquely identifies the external batch
  - `batch_notes` string, 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' | 'ShipStation' | '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, the ShipStation API itself, or the underlying ShipEngine platform.
    - `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' | 'freight_connection_inactive' | 'freight_provider_id_required' | 'freight_shipment_not_found' | 'freight_tracking_not_available' | 'freight_tracking_not_found' | 'freight_shipment_not_batchable', required — The error code specified for the failed API Call
    - `message` string, required — An error message associated with the failed API call
    - `field_name` string — The name of the field that caused the error (only present for validation errors)
    - `field_value` string — The invalid value that was provided for the field (only present for validation errors)
  - `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 — The instructions for the paperless download.
    - `handoff_code` string — 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 API returns a 404 response when no `batch` corresponds to the `external_batch_id` provided.
- `500` — The request was successful.

---

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