batches

Get batch by ID

Changed on
<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>

Get batch details for a specific batch ID.

get/v2/batches/{batch_id}

Request

  • Base URL
    https://api.shipstation.com
  • URL
    https://api.shipstation.com/v2/batches/{batch_id}
  • Auth
    API key in header api-key

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> 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 nullable required

A string that uniquely identifies the external batch

batch_notesstring nullable required

Custom notes you can add for each created batch

assigned_userstring uuid nullable

The ID of the user assigned to the batch, or null if no user is assigned.

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",
  "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": [
    {
      "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"
  },
  "packing_slip_download": {
    "href": "https://example.com/resource",
    "type": "child"
  },
  "form_download": {
    "href": "https://example.com/resource",
    "type": "child"
  },
  "paperless_download": {
    "href": "https://example.com/resource",
    "instructions": "any instructions",
    "handoff_code": "122334"
  }
}

Changes

  • 4e29670aa28dRevision 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 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

  • bf3618aaf7e1Revision changes
    • breaking

      the response property / became nullable for the status

    • breaking

      the response property / became nullable for the status

    • breaking

      the response property /// became nullable for the status

    • breaking

      the response property /// became nullable for the status

    • breaking

      added subschema #2 to the / response property oneOf list for the response status

    • info

      removed from the / response property allOf list for the response status