batches

Create a batch

Changed on Oct 22, 2026

Create a Batch

post/v1/batches

Request

Base URL: https://api.shipengine.com
URL: https://api.shipengine.com/v1/batches
Auth: API key in header API-Key

Request body

external_batch_idstring

A string that uniquely identifies a ShipEngine 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' | '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> stamps_com <br> ups <br> usps

batch_idstring required

A string that uniquely identifies a ShipEngine 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 nullable required

The date and time the batch was processed in ShipEngine

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_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": [
    {
      "error_source": "shipengine",
      "error_type": "validation",
      "error_code": "invalid_field_value",
      "message": "Body of request cannot be null.",
      "carrier_id": "se-28529731",
      "carrier_code": "dhl_express",
      "field_name": "shipment.ship_to.phone_number"
    }
  ],
  "warnings": 1,
  "completed": 1,
  "forms": 3,
  "count": 2,
  "batch_shipments_url": {
    "href": "https://example.com/resource"
  },
  "batch_labels_url": {
    "href": "https://example.com/resource"
  },
  "batch_errors_url": {
    "href": "https://example.com/resource"
  },
  "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"
  },
  "form_download": {
    "href": "https://example.com/resource"
  },
  "paperless_download": {
    "href": "https://example.com/resource"
  }
}

Changes

Oct 22, 2026e998dffc42be 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 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 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
- warning
  added the new sales_order_link_required enum value to the // response property for the response status
Oct 9, 2026020f57d6f5b8 Revision changes
- breaking
  removed from the request body oneOf list
- breaking
  the request's body type changed from no type to object
- breaking
  the // response's property type changed from no type to object for status
- breaking
  the // response's property type changed from no type to object for status
- breaking
  the / response's property type changed from no type to object for status
- breaking
  the / response's property type changed from no type to object for status
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the optional property /// to the response with the status
- info
  added the optional property /// to the response with the status
- info
  added the optional property /// to the response with the status
- info
  added the optional property /// to the response with the status
- info
  added the optional property /// to the response with the status
- info
  added the optional property /// to the response with the status
- info
  added the optional property // to the response with the status
- info
  added the optional property // to the response with the status
- info
  added the optional property // to the response with the status
- info
  added the optional property // to the response with the status
- info
  added the optional property // to the response with the status
- info
  added the optional property // to the response with the 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
- info
  removed from the / response property allOf list for the response status
- info
  removed from the / response property allOf list for the response status
- info
  added the required property /// to the response with the status
- info
  added the required property /// to the response with the status
- info
  added the required property /// to the response with the status
- info
  added the required property /// to the response with the status
- info
  added the required property /// to the response with the status
- info
  added the required property /// to the response with the status
- info
  added the required property /// to the response with the status
- info
  added the required property /// to the response with the status
- info
  added the required property // to the response with the status
- info
  added the required property // to the response with the status
- info
  added the required property // to the response with the status
- info
  added the required property // to the response with the status
- info
  added the required property // to the response with the status
- info
  added the required property // to the response with the status
- info
  added the required property // to the response with the status
- info
  added the required property // to the response with the status

Operation history (6 revisions)