---
title: "Create a Batch of Shipments"
method: POST
path: "/2024-09/batches/shipments"
tags: ["Batches"]
---

# Create a Batch of Shipments

`POST /2024-09/batches/shipments`

## Request

- Base URL: `https://public-api.easyship.com`
- URL: `https://public-api.easyship.com/2024-09/batches/shipments`
- Auth: HTTP bearer

Create a batch of shipments and schedule it for processing.

Required authorization scopes: `public.batch:write`, `public.shipment:write` and `public.label:write` if a label(s) will be created during the batch processing.

## Request body

- BatchShipmentsCreate: Batch Shipments Create
  - `defaults` object: Default settings for each shipment (can be override on the individual shipment)
    - `origin_address_id` string, uuid, required
    - `sender_address_id` string, uuid, required
    - `return_address_id` string, uuid, required
    - `incoterms` Incoterms (unresolved $ref)
    - `regulatory_identifiers` RegulatoryIdentifiers (unresolved $ref)
    - `buyer_regulatory_identifiers` BuyerRegulatoryIdentifiers (unresolved $ref)
    - `courier_settings` CourierSettings (unresolved $ref)
    - `shipping_settings` object
      - `additional_services` AdditionalServices (unresolved $ref)
      - `units` Units: Units
        - `weight` 'kg' | 'g' | 'lb' | 'oz': Unit of weight values provided. Options: `kg` / `g` / `lb` / `oz` (Default: `kg`). Unit of values in the response will be in `kg`.
        - `dimensions` 'cm' | 'in': Unit of dimension values provided. Options: `cm` / `in` (Default: `cm`) Unit of values in the response will be in `cm`.
      - `buy_label` BuyLabel (unresolved $ref)
      - `b13a_filing` B13aFiling (unresolved $ref)
      - `printing_options` PrintingOptions (unresolved $ref)
      - `scheduled_ship_date` ScheduledShipDate (unresolved $ref)
  - `shipments` object[]
    - `origin_address_id` string, uuid
    - `sender_address_id` string, uuid
    - `return_address_id` string, uuid
    - `destination_address` DestinationAddress, required
      - `line_1` string: First line of the street address
      - `line_2` string, nullable: Second line of the street address
      - `line_3` string, nullable: Third line of the street address. Saved and returned on shipments only (ignored by rates and trackings). Not every courier includes it on the label, so it may be ignored if the selected courier does not support a third address line.
      - `state` string, nullable: State, Province, or other top-level administrative region. Mandatory for these countries: AU, CA, CN, ID, MX, MY, TH, US, VN. Use abbreviations for naming the state if possible (2 letters for the US/CA, 2 or 3 letters for AU). For countries using provinces, use the full province names.
      - `city` string: City or Suburb
      - `postal_code` string: Postal code. Mandatory for most countries (if not applicable, for example Hong Kong, leave null or 0)
      - `country_alpha2` 'AD' | 'AE' | 'AF' | 'AG' | 'AI' | 'AL' | 'AM' | 'AN' | 'AO' | 'AQ' | 'AR' | 'AS' | 'AT' | 'AU' | 'AW' | 'AX' | 'AZ' | 'BA' | 'BB' | 'BD' | 'BE' | 'BF' | 'BG' | 'BH' | 'BI' | 'BJ' | 'BL' | 'BM' | 'BN' | 'BO' | 'BQ' | 'BR' | 'BS' | 'BT' | 'BV' | 'BW' | 'BY' | 'BZ' | 'CA' | 'CC' | 'CD' | 'CF' | 'CG' | 'CH' | 'CI' | 'CK' | 'CL' | 'CM' | 'CN' | 'CO' | 'CR' | 'CU' | 'CV' | 'CW' | 'CX' | 'CY' | 'CZ' | 'DE' | 'DJ' | 'DK' | 'DM' | 'DO' | 'DZ' | 'EC' | 'EE' | 'EG' | 'EH' | 'ER' | 'ES' | 'ET' | 'FI' | 'FJ' | 'FK' | 'FM' | 'FO' | 'FR' | 'GA' | 'GB' | 'GD' | 'GE' | 'GF' | 'GG' | 'GH' | 'GI' | 'GL' | 'GM' | 'GN' | 'GP' | 'GQ' | 'GR' | 'GS' | 'GT' | 'GU' | 'GW' | 'GY' | 'HK' | 'HM' | 'HN' | 'HR' | 'HT' | 'HU' | 'ID' | 'IE' | 'IL' | 'IM' | 'IN' | 'IO' | 'IQ' | 'IR' | 'IS' | 'IT' | 'JE' | 'JM' | 'JO' | 'JP' | 'KE' | 'KG' | 'KH' | 'KI' | 'KM' | 'KN' | 'KP' | 'KR' | 'KW' | 'KY' | 'KZ' | 'LA' | 'LB' | 'LC' | 'LI' | 'LK' | 'LR' | 'LS' | 'LT' | 'LU' | 'LV' | 'LY' | 'MA' | 'MC' | 'MD' | 'ME' | 'MF' | 'MG' | 'MH' | 'MK' | 'ML' | 'MM' | 'MN' | 'MO' | 'MP' | 'MQ' | 'MR' | 'MS' | 'MT' | 'MU' | 'MV' | 'MW' | 'MX' | 'MY' | 'MZ' | 'NA' | 'NC' | 'NE' | 'NF' | 'NG' | 'NI' | 'NL' | 'NO' | 'NP' | 'NR' | 'NU' | 'NZ' | 'OM' | 'PA' | 'PE' | 'PF' | 'PG' | 'PH' | 'PK' | 'PL' | 'PM' | 'PN' | 'PR' | 'PS' | 'PT' | 'PW' | 'PY' | 'QA' | 'RE' | 'RO' | 'RS' | 'RU' | 'RW' | 'SA' | 'SB' | 'SC' | 'SD' | 'SE' | 'SG' | 'SH' | 'SI' | 'SJ' | 'SK' | 'SL' | 'SM' | 'SN' | 'SO' | 'SR' | 'SS' | 'ST' | 'SV' | 'SX' | 'SY' | 'SZ' | 'TC' | 'TD' | 'TF' | 'TG' | 'TH' | 'TJ' | 'TK' | 'TL' | 'TM' | 'TN' | 'TO' | 'TR' | 'TT' | 'TV' | 'TW' | 'TZ' | 'UA' | 'UG' | 'UM' | 'US' | 'UY' | 'UZ' | 'VA' | 'VC' | 'VE' | 'VG' | 'VI' | 'VN' | 'VU' | 'WF' | 'WS' | 'YE' | 'YT' | 'ZA' | 'ZM' | 'ZW': Country Code in Alpha-2 format (ISO 3166-1)
      - `company_name` string, nullable: The company or organization at the address
      - `contact_name` string: The full name of a person at the address
      - `contact_phone` string: Phone number used to reach the person in contact_name (may or may not be SMS-ready)
      - `contact_email` string, email: Email address used to reach the person in `contact_name`
      - `delivery_instructions` string, nullable: Delivery instructions for the address, see [Delivery Instructions](https://developers.easyship.com/page/delivery-instructions).
    - `metadata` Metadata (unresolved $ref)
    - `set_as_residential` SetAsResidential (unresolved $ref)
    - `consignee_tax_id` ConsigneeTaxId (unresolved $ref)
    - `eei_reference` EeiReference (unresolved $ref)
    - `regulatory_identifiers` RegulatoryIdentifiers (unresolved $ref)
    - `buyer_regulatory_identifiers` BuyerRegulatoryIdentifiers (unresolved $ref)
    - `incoterms` Incoterms (unresolved $ref)
    - `insurance` Insurance (unresolved $ref)
    - `order_data` OrderData (unresolved $ref)
    - `courier_settings` CourierSettings (unresolved $ref)
    - `shipping_settings` object
      - `additional_services` AdditionalServices (unresolved $ref)
      - `units` Units: Units
        - `weight` 'kg' | 'g' | 'lb' | 'oz': Unit of weight values provided. Options: `kg` / `g` / `lb` / `oz` (Default: `kg`). Unit of values in the response will be in `kg`.
        - `dimensions` 'cm' | 'in': Unit of dimension values provided. Options: `cm` / `in` (Default: `cm`) Unit of values in the response will be in `cm`.
      - `buy_label` BuyLabel (unresolved $ref)
      - `b13a_filing` B13aFiling (unresolved $ref)
      - `printing_options` PrintingOptions (unresolved $ref)
      - `scheduled_ship_date` ScheduledShipDate (unresolved $ref)
    - `parcels` object[], required
      - `total_actual_weight` TotalActualWeight (unresolved $ref)
      - `box` Box (unresolved $ref)
      - `items` object[]: Array of all shipment items
        - `product` Product, required (unresolved $ref)
        - `description` Description (unresolved $ref)
        - `hs_code` HsCode (unresolved $ref)
        - `category` Category (unresolved $ref)
        - `quantity` Quantity (unresolved $ref)
        - `declared_currency` DeclaredCurrency (unresolved $ref)
        - `declared_customs_value` DeclaredCustomsValue (unresolved $ref)

## Response `202`

batch successfully created

- BatchSingle: Batch
  - `batch` BatchSingle (recursive)
  - `meta` Meta
    - `request_id` string: An unique ID represent the request.

## Other responses

- `422`: invalid params

## Changes

- **2026-11-03** `b47b54b748a7`: 3 info
  - added the new optional request property `defaults/shipping_settings/scheduled_ship_date`
  - added the new optional request property `shipments/items/destination_address/allOf[#/components/schemas/DestinationAddress]/line_3`
  - added the new optional request property `shipments/items/shipping_settings/scheduled_ship_date`

[Operation history](https://skmtc.dev/easyship/apis/easyship-public-api/changes/2024-09/batches/shipments/post.md)

---

[API](https://skmtc.dev/easyship/apis/easyship-public-api.md) - [All operations](https://skmtc.dev/easyship/apis/easyship-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/easyship/apis/easyship-public-api/revisions/b47b54b748a7?raw)