batches

Create a batch

Changed on Oct 22, 2026

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

Create a batch containing multiple labels.

post/v2/batches

Request

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

Request body

external_batch_idstring

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

batch_notesstring

Add custom messages for a particular batch

assigned_userstring uuid

Assign a user to the batch at creation time. The user must be an active member of your account.

shipment_idsSeId[]

Array of shipment IDs used in the batch

rate_idsSeId[]

Array of rate IDs used in the batch

Example request

{
  "external_batch_id": "se-28529731",
  "batch_notes": "This is my batch",
  "assigned_user": "a2df9fa5-b7ee-467f-be4e-9c660542c187",
  "shipment_ids": [
    "se-28529731"
  ],
  "rate_ids": [
    "se-28529731"
  ],
  "process_labels": {
    "create_batch_and_process_labels": true,
    "ship_date": "2018-09-23T15:00:00.000Z",
    "generate_packing_slips": true
  }
}

Response

The requested object creation 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 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> 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

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

Oct 22, 20264e29670aa28d 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 16, 2026bf3618aaf7e1 Revision 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
  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
- 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
- info
  removed from the / response property allOf list for the response status

Operation history (7 revisions)