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
• Request
• Request Example
• Response
• Response Example

Endpoint

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

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