Sign in
latestOpenAPI 3.1.0MIT2026-08-221643491.4 MB

d3d8c21cd227

batches

Get batch by external 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

get/v2/batches/external_batch_id/{external_batch_id}

Response

The request was a success.

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 FormatSupported Carriers
pdfAll carriers
pngfedex <br> stamps_com <br> ups <br> usps
zplaccess_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_idstring required

A string that uniquely identifies a ShipStation resource, such as a carrier, label, shipment, etc.

batch_numberstring required

The batch number.

external_batch_idstring required

A string that uniquely identifies the external batch

batch_notesstring required

Custom notes you can add for each created batch

created_atstring date-time required

An ISO 8601 string that represents a date and time.

processed_atstring date-time required

An ISO 8601 string that represents a date and time.

errorsinteger required

The number of errors that occurred while generating the batch

warningsinteger required

The number of warnings that occurred while generating the batch

completedinteger required

The number of labels generated in the batch

formsinteger required

The number of forms for customs that are available for download

countinteger required

The total of errors, warnings, and completed properties

status'open' | 'queued' | 'processing' | 'completed' | 'completed_with_errors' | 'archived' | 'notifying' | 'invalid' required

The possible batch status values

Example response

{
  "batch_id": "se-28529731",
  "batch_number": "123456",
  "external_batch_id": "12323aaaar",
  "batch_notes": "Batch for morning shipment",
  "created_at": "2018-09-23T15:00:00.000Z",
  "processed_at": "2018-09-23T15:00:00.000Z",
  "errors": 2,
  "process_errors": [
    {
      "message": "Body of request cannot be null.",
      "field_name": "inventory_warehouse_id",
      "field_value": "invalid-id"
    }
  ],
  "warnings": 1,
  "completed": 1,
  "forms": 3,
  "count": 2,
  "batch_shipments_url": {
    "href": "https://example.com/resource",
    "type": "child"
  },
  "batch_labels_url": {
    "href": "https://example.com/resource",
    "type": "child"
  },
  "batch_errors_url": {
    "href": "https://example.com/resource",
    "type": "child"
  },
  "label_download": {
    "href": "https://example.com/resource",
    "pdf": "https://example.com/resource",
    "png": "https://example.com/resource",
    "zpl": "https://example.com/resource"
  },
  "form_download": {
    "href": "https://example.com/resource",
    "type": "child"
  },
  "paperless_download": {
    "href": "https://example.com/resource",
    "instructions": "any instructions",
    "handoff_code": "122334"
  }
}