---
title: "Create a batch"
method: POST
path: "/v2/batches"
tags: ["batches"]
---

# Create a batch

`POST /v2/batches`

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

## Request body

- union
  - CreateBatchRequestBody — A create batch request body
    - `external_batch_id` string — A string that uniquely identifies a ShipStation resource, such as a carrier, label, shipment, etc.
    - `batch_notes` string — Add custom messages for a particular batch
    - `shipment_ids` SeId[] — Array of shipment IDs used in the batch
    - `rate_ids` SeId[] — Array of rate IDs used in the batch
  - CreateAndProcessBatchRequestBody — A create and process batch request body
    - `external_batch_id` string — A string that uniquely identifies a ShipStation resource, such as a carrier, label, shipment, etc.
    - `batch_notes` string — Add custom messages for a particular batch
    - `shipment_ids` SeId[] — Array of shipment IDs used in the batch
    - `rate_ids` SeId[] — Array of rate IDs used in the batch
    - `process_labels` object — The information used to process the batch
      - `create_batch_and_process_labels` boolean — When 'true', the batch will be enqueued for processing
      - `ship_date` string, date-time — An [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) string that represents a date and time.
      - `label_layout` '4x6' | 'letter' — 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' — 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> `rr_donnelley` <br> `stamps_com` <br> `ups` <br> `usps`
      - `display_scheme` 'label' | 'paperless' | 'label_and_paperless' — The display format that the label should be shown in.

## Response `200`

The requested object creation was a success.

- CreateBatchResponseBody — Batches are an advanced feature of ShipStation designed for users who need to generate hundreds or thousands of labels at a time.
  - `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> `rr_donnelley` <br> `stamps_com` <br> `ups` <br> `usps`
  - `batch_id` string, required — A string that uniquely identifies a ShipStation resource, such as a carrier, label, shipment, etc.
  - `batch_number` string, required — The batch number.
  - `external_batch_id` string, required — A string that uniquely identifies the external batch
  - `batch_notes` string, required — Custom notes you can add for each created batch
  - `created_at` string, date-time, required — An [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) string that represents a date and time.
  - `processed_at` string, date-time, required — An [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) string that represents a date and time.
  - `errors` integer, required — The number of errors that occurred while generating the batch
  - `process_errors` Error[], required — The errors associated with the failed API call
    - `error_source` 'carrier' | 'order_source' | 'ShipStation' | 'shipengine', required — The source of the error, as indicated by the name this informs us if the API call failed because of the carrier, the order source, the ShipStation API itself, or the underlying ShipEngine platform.
    - `error_type` 'account_status' | 'business_rules' | 'validation' | 'security' | 'system' | 'integrations', required — The type of error
    - `error_code` 'auto_fund_not_supported' | 'batch_cannot_be_modified' | 'carrier_conflict' | 'carrier_disconnected' | 'carrier_not_connected' | 'carrier_not_supported' | 'confirmation_not_supported' | 'default_warehouse_cannot_be_deleted' | 'field_conflict' | 'field_value_required' | 'forbidden' | 'identifier_conflict' | 'identifiers_must_match' | 'insufficient_funds' | 'invalid_address' | 'invalid_billing_plan' | 'invalid_field_value' | 'invalid_identifier' | 'invalid_status' | 'invalid_string_length' | 'label_images_not_supported' | 'meter_failure' | 'order_source_not_active' | 'rate_limit_exceeded' | 'refresh_not_supported' | 'request_body_required' | 'return_label_not_supported' | 'settings_not_supported' | 'subscription_inactive' | 'terms_not_accepted' | 'tracking_not_supported' | 'trial_expired' | 'unauthorized' | 'unknown' | 'unspecified' | 'verification_failure' | 'warehouse_conflict' | 'webhook_event_type_conflict' | 'customs_items_required' | 'incompatible_paired_labels' | 'invalid_charge_event' | 'invalid_object' | 'no_rates_returned' | 'freight_connection_inactive' | 'freight_provider_id_required' | 'freight_shipment_not_found' | 'freight_tracking_not_available' | 'freight_tracking_not_found' | 'freight_shipment_not_batchable', required — The error code specified for the failed API Call
    - `message` string, required — An error message associated with the failed API call
    - `field_name` string — The name of the field that caused the error (only present for validation errors)
    - `field_value` string — The invalid value that was provided for the field (only present for validation errors)
  - `warnings` integer, required — The number of warnings that occurred while generating the batch
  - `completed` integer, required — The number of labels generated in the batch
  - `forms` integer, required — The number of forms for customs that are available for download
  - `count` integer, required — The total of errors, warnings, and completed properties
  - `batch_shipments_url` OptionalLink, required — A link to a related resource, or an empty object if there is no resource to link to
    - `href` string, url — A URL
    - `type` string — The type of resource, or the type of relationship to the parent resource
  - `batch_labels_url` OptionalLink, required — A link to a related resource, or an empty object if there is no resource to link to
    - `href` string, url — A URL
    - `type` string — The type of resource, or the type of relationship to the parent resource
  - `batch_errors_url` OptionalLink, required — A link to a related resource, or an empty object if there is no resource to link to
    - `href` string, url — A URL
    - `type` string — The type of resource, or the type of relationship to the parent resource
  - `label_download` LabelDownload, required — Reference to the various downloadable file formats for the generated label
    - `href` string, url — A URL
    - `pdf` string, url — A URL
    - `png` string, url — A URL
    - `zpl` string, url — A URL
  - `form_download` OptionalLink, required — A link to a related resource, or an empty object if there is no resource to link to
    - `href` string, url — A URL
    - `type` string — The type of resource, or the type of relationship to the parent resource
  - `paperless_download` PaperlessDownload, required — The paperless details which may contain elements like `href`, `instructions` and `handoff_code`.
    - `href` string, url — A URL
    - `instructions` string — The instructions for the paperless download.
    - `handoff_code` string — The handoff code for the paperless download.
  - `status` 'open' | 'queued' | 'processing' | 'completed' | 'completed_with_errors' | 'archived' | 'notifying' | 'invalid', required — The possible batch status values

## Other responses

- `207` — The request was a partial success. It contains results, as well as processing errors.
- `400` — The request contained errors.
- `500` — The request was successful.

---

[API](https://skmtc.net/shipstation/apis/shipstation-api-v2.md) · [All operations](https://skmtc.net/shipstation/apis/shipstation-api-v2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/shipstation/shipstation-api-v2/revisions/d3d8c21cd227/schema)