Sign in

v1

latestOpenAPI 3.0.02026-07-1397337495.2 KB
batches

Create A Batch

Create a Batch

post/v1/batches

Request body

OR

Example request

{
  "external_batch_id": "se-28529731",
  "batch_notes": "This is my batch",
  "shipment_ids": [
    "se-28529731"
  ],
  "rate_ids": [
    "se-28529731"
  ]
}

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

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_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.",
      "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": "http://api.shipengine.com/v1/labels/se-28529731"
  },
  "batch_labels_url": {
    "href": "http://api.shipengine.com/v1/labels/se-28529731"
  },
  "batch_errors_url": {
    "href": "http://api.shipengine.com/v1/labels/se-28529731"
  },
  "label_download": {
    "href": "http://api.shipengine.com/v1/labels/se-28529731",
    "pdf": "http://api.shipengine.com/v1/labels/se-28529731",
    "png": "http://api.shipengine.com/v1/labels/se-28529731",
    "zpl": "http://api.shipengine.com/v1/labels/se-28529731"
  },
  "form_download": {
    "href": "http://api.shipengine.com/v1/labels/se-28529731"
  },
  "paperless_download": {
    "href": "http://api.shipengine.com/v1/labels/se-28529731"
  }
}