Create Batch

{primary} Beta Feature: The Batch Shipments feature is currently in beta and only available for your own USPS carrier account integrations.

This method is used to create a new shipment batch with multiple shipments. Items are validated asynchronously after creation.

{info} Batch shipments support a maximum of 1,000 items per batch. Only PDF label format is supported.

Endpoint

Method URI Headers
POST /batches default

Request

Field Required Type Description
shipper_id Yes Integer The ID of the shipper to use for this batch. You can find your shipper ID in the shippers endpoint.
service Yes String The service code to use for all shipments in the batch. Please refer to service-names.
batch_shipments [] Yes Array Array of shipment objects to include in the batch.
+from_address_id No* Integer This field is used to identify sender address. You can fetch your saved addresses from address-book. Not required if a "from_address" object was used.

Note: If both "from_address_id" and "from_address" fields are defined system will prioritise the "from_address_id"
+return_address_id No Integer This field is used to identify return address. You should use the address which is in your saved from addresses. You can fetch your saved from addresses from address-book.
+from_address {} No* Object Sender address container. Condition: only required if a "from_address_id" was not used
++name Yes String Name of the sender
++attention No String Attention of the sender
++street_1 Yes String Street line 1
++street_2 No String Street line 2
++street_3 No String Street line 3
++city Yes String City
++zip Yes String Postal Zip code
++state No* String State - This field is required for US or Canada addresses please refer to country-codes
++country Yes String Country (code) for the list please refer to country-codes
++telephone Yes String Telephone Number - This field will will avoid special characters (max 10-15 digits)
++email No String Email
+to_address {} Yes Object Receiver address container
++name Yes String Name of the receiver
++attention No String Attention of the receiver
++street_1 Yes String Street line 1
++street_2 No String Street line 2
++street_3 No String Street line 3
++city Yes String City
++zip Yes String Postal Zip code
++state No* String State - This field is required for US or Canada addresses please refer to country-codes
++country Yes String Country (code) for the list please refer to country-codes
++telephone Yes String Telephone Number - This field will will avoid special characters (max 10-15 digits)
++email No String Email
+weight_unit No String By default, weight unit is taken from your preferences. However, it can be overwritten using this field. Valid values: LBS and KG
+length_unit No String By default, length unit is taken from your preferences. However, it can be overwritten using this field. Valid values: IN and CM
+package_list [] Yes Array An array containing all the package information
++count Yes Integer Pieces count
++box_type No String Carrier box types for the list please refer to Parcel Box Types
++length Yes Float Length
++width Yes Float Width
++height Yes Float Height
++weight Yes Float Weight
++reference_1 No String Reference that will appear on the label
++reference_2 No String Reference that will appear on the label
++insurance No Boolean Default is false. Setting this to true would require items information
++is_hazmat No Boolean If the item is hazmat, default is false
++signature No String Default is no_signature, other options are adult_signature and signature
++items [] No* Array An array containing all items information. Condition: only required on international shipments and shipments with insurance
+++quantity No* Integer Quantity of the item Condition: only required when items [] is used
+++price No* Float Price of the item Condition: only required when items [] is used
+++country_of_manufacture No* String Where the item is manufactured needs to be a country code please refer to country-codes. Condition: only required when items [] is used
+++sku No* String SKU. Condition: only required when items [] is used
+++hs_code No* String HS Tariff Code of item. The HS tariff code is an internationally standardized classification system for traded goods, used to determine tariffs and customs duties. Condition: only required when items [] is used
+++description No* String A brief description for customs. Condition: only required when items [] is used
+++content_type No* String Default is Merchandise, acceptable values are Merchandise, Gift, Documents, Sample. Condition: only required when items [] is used
+extra_services [] No Array An array containing all the extra services
++saturday_delivery No Boolean Default is false.
++certified_mail No Boolean Default is false.
++return_receipt No Boolean Default is false.
++return_receipt_electronic No Boolean Default is false.
++restricted_delivery No Boolean Default is false.
+customs_details {} No Object Customs details container
++bill_type No String Either DDU or DDP should be selected, default is DDP.
++tax_id_type No String Either VAT, EIN or SSN should be used, default is null.
++tax_id No String Default is null.
++issuer_country No String Default is null.
++aes_itn No String Default is null.

Request Example

{
    "shipper_id": 123,
    "service": "USPS-3",
    "batch_shipments": [
        {
            "from_address_id": 1387235969,
            "to_address": {
                "name": "Jane Smith",
                "street_1": "456 Oak Ave",
                "city": "Los Angeles",
                "state": "CA",
                "zip": "90001",
                "country": "US",
                "telephone": "5559876543"
            },
            "package_list": [
                {
                    "count": 1,
                    "length": 10,
                    "width": 8,
                    "height": 4,
                    "weight": 1,
                    "reference_1": "ORDER-001"
                }
            ]
        },
        {
            "from_address_id": 1387235969,
            "to_address": {
                "name": "Bob Johnson",
                "street_1": "789 Pine Rd",
                "city": "Chicago",
                "state": "IL",
                "zip": "60601",
                "country": "US",
                "telephone": "5551112222"
            },
            "package_list": [
                {
                    "count": 1,
                    "length": 12,
                    "width": 10,
                    "height": 6,
                    "weight": 2,
                    "reference_1": "ORDER-002"
                }
            ]
        }
    ]
}

Response

Field Type Description
id String The batch hash ID.
status String Current batch status. Will be validating immediately after creation.
default_service String The service code set for this batch.
default_shipper_id String The shipper hash ID for this batch.

Response Examples

Successful

{
    "success": true,
    "data": {
        "id": "12345678",
        "status": "validating",
        "default_service": "USPS-3",
        "default_shipper_id": "99999999"
    }
}

Failed

{
    "success": false,
    "message": "Shipper not found or does not meet requirements for batch shipping."
}