# Overview The Batch Shipment APIs provide operations to create, import, process, track, and manage shipments in bulk. These APIs enable submission of multiple shipments in a single request or through file-based import, supporting high-volume shipping workflows. Batch shipment processing supports two modes: - **Synchronous bulk** creation using API payloads - **Asynchronous batch** processing using file import (CSV via S3 URL) The APIs also support ERR (Electronic Return Receipt) shipments, allowing generation of compliant return receipt documents for USPS shipments. **Batch** A collection of shipments grouped under a single processing request, identified by batchId. **Root Level attributes (Default)** Defines common attributes (e.g., carrier, service, parcel type) applied to all shipments in the batch. **Shipment Level attributes** Defines attributes specific to individual shipments. Values provided at this level override root-level defaults. **Combination Rule** `carrierAccountId`, `parcelType`, and `serviceId` must be provided together at the shipment level. Partial values result in validation errors. **Batch ID (batchId)** A system-generated identifier used to process, track, and manage batch operations. - Bulk shipments can be created via API payload or imported using a CSV file hosted on S3 - Batch import generates a batchId used for further processing and tracking - Batch processing is triggered explicitly using the `Process Batch API` - Batch status and shipment-level results can be retrieved using `batchId` - Shipments within a batch can be voided either partially (specific shipment IDs) or entire batch - ERR batch supports additional document formats such as **Shipping Label** and **Coversheet** Version: 1.0.0 ## Servers ``` https://api-dev.sendpro360.pitneycloud.com/shipping ``` ``` https://api-qa.sendpro360.pitneycloud.com/shipping ``` Sandbox Server ``` https://api-sandbox.sendpro360.pitneybowes.com/shipping ``` Production Server (uses live data) ``` https://api.sendpro360.pitneybowes.com/shipping ``` Sandbox Server for Canada ``` https://api-ppd.shipping360.pitneybowes.com/ca/shipping ``` Production Server for Canada ``` https://api.shipping360.pitneybowes.com/ca/shipping ``` ## Security ### bearerAuth Type: http Scheme: bearer ## Download OpenAPI description [Overview](https://docs.sendpro360.pitneycloud.com/_bundle/openapi/batchshipping.yaml) ## Batch Shipment These APIs support both synchronous bulk shipment creation and asynchronous batch processing using file-based import. They provide capabilities to track batch execution status, retrieve shipment-level results, and perform actions such as voiding shipments, enabling efficient handling of high-volume shipping workflows. ### Create Bulk Shipments - [POST /api/v1/bulkShipments](https://docs.sendpro360.pitneycloud.com/openapi/batchshipping/batch-shipment/createbulkshipmentsapi.md): This API "Create Bulk Shipments" operation requires the following information: - Recipient (Single or Multiple) - Carrier - Service - Parcel Type, and - Special Service The API works at two levels: Shipment level and Root level. Root level is marked as Default, where multiple shipments are processed and entities are common for all shipments. While at Shipment level, entities might differ. User can either define values for CarrierAccountID, ParcelType, ServiceID, and SpecialService respectively at the Root level for all shipments, or mention the values at Shipment level, i.e., for individual shipment(s). If user does not provide values for the above-mentioned fields combinedly at Shipment level, then the default values for these fields provided at Root level will be considered. While, if user provides these values combinedly at Shipment Level for individual shipment(s), it will override the values defined at Root level. Condition: The fields CarrierAccountID, ParcelType, ServiceID* are treated as a combination, and values against each field must be provided if user selects Shipment level. In case any of these field(s) out of the mentioned combination is/are missing, it will return validation error.* ### Create Bulk Shipments ERR - [POST /api/v1/err/bulkShipments](https://docs.sendpro360.pitneycloud.com/openapi/batchshipping/batch-shipment/createbulkshipmentsapierr.md): ERR (Electronic Return Receipt) is an official United States Postal Service® (USPS) document designed to be equivalent to the hardcopy 'green card' Return Receipt. It provides the following information: - Name of the Recipient - Time when article is delivered - Signature (image) of the Recipient - Address where the item is delivered, and - Date when the article gets delivered. ERR is combined with certain classes and categories of mails, which are as follow: - First-Class Mail® - Priority Mail® ERR Batch supports two types of Shipment Document format: - Shipping Label - Coversheet This API "Create Bulk Shipments with ERR" operation requires the following information: - Recipient (Single or Multiple) - Carrier - USPS - Service - Parcel Type, and - Special Service. The ERR API works at two levels: Shipment level and Root level. Root level is marked as Default, where multiple shipments are processed and entities are common for all shipments. While at Shipment level, entities might differ. User can either define values for CarrierAccountID, ParcelType, ServiceID, and SpecialService respectively at the Root level for all shipments, or mention the values at Shipment level, i.e., for individual shipment(s). If user does not provide values for the above-mentioned fields combinedly at Shipment level, then the default values for these fields provided at Root level will be considered. While, if user provides these values combinedly at Shipment Level for individual shipment(s), it will override the values defined at Root level. Condition: The fields CarrierAccountID, ParcelType, ServiceID are treated as a combination, and values against each field must be provided if user selects Shipment level. In case any of these field(s) out of the mentioned combination is/are missing, it will return validation error. ### Bulk Import Shipments - [POST /api/v1/shipments/importUrl](https://docs.sendpro360.pitneycloud.com/openapi/batchshipping/batch-shipment/bulkimportapi.md): "This operation imports the .CSV file for Bulk Shipment, which includes fields essential to create Bulk Shipments. The payload contains the following essential fields in .CSV file, used for shipment transactions: - Carrier Account - Output format, which includes Shipping Label and Coversheet - Services, and - Special Services User stores this information in AWS-S3 which in turn provides URL to users. After submitting Batch, user uploads the S3 returned URL along with the .CSV file, which generates BatchID. The same BatchID can be used to track the status of BulkImport." ### Bulk Import Shipments ERR - [POST /api/v1/err/shipments/importUrl](https://docs.sendpro360.pitneycloud.com/openapi/batchshipping/batch-shipment/bulkimportapierr.md): This operation imports the .CSV file which includes fields required for creating ERR (Electronic Return Receipt) Bulk Shipments. The payload, which is used for shipment transactions, contains the following essential information in .CSV file: - Carrier Account - Output format: Shipping Label and Coversheet - Services, and - Special Services The above-mentioned information are stored in AWS-S3 which in turn provides URL to users. When Batch is submitted, S3 returned URL along with .CSV file are uploaded, which generates BatchID. The same BatchID is used to track the status of BulkImport. ### Process Batch - [POST /api/v1/shipments/batch/{batchId}/process](https://docs.sendpro360.pitneycloud.com/openapi/batchshipping/batch-shipment/processbatchapi.md): This operation processes (executes) the existing Batch. The payload for this endpoint needs only an empty JSON object and no additional data is required in the request body. The BatchID parameter located in the endpoint specifies which batch of shipments to process. ### Void Batch Shipping Labels - [POST /api/v1/shipments/batch/{batchId}/void](https://docs.sendpro360.pitneycloud.com/openapi/batchshipping/batch-shipment/voidshippinglabel.md): This operation cancels (voids) shipments which are created using the Batch API operation createBulkShipments. If user wants to cancel specific shipment(s) of the Batch, then s/he needs to pass the Shipment ID for the selected shipments in the shipmentIDs array. While if user wants to cancel all shipments of the Batch, then s/he does not need to provide any Shipment ID in the array under request body. Key Considerations - Cancelation must occur before the shipment is picked up or processed by the carrier. - Refunds are only applicable for unused labels. Voiding a used label may result in penalties or billing. - Refunds are subject to the policies of the applicable carrier. - Refund requests must be submitted within 30 days from the date the label was printed. - USPS may take up to 30 days to process the refund. - The refund status can be tracked on the History page. - Approved refunds will be credited back to the USPS postage balance. - The label status will change to Refunded once the refund is processed. - For unused post-paid labels, you must void them. Voiding avoids billing for the label and allows the carrier to maintain an accurate count for pickups. - Always destroy voided labels to prevent accidental use. If a voided label is shipped, you will be billed for the label. - Once a refund has been claimed, you cannot use the shipping label for sending packages. It will be rejected. - Submitting false or fraudulent refund claims is a federal offense, punishable by fines or imprisonment. ### Get Batch Status - [GET /api/v1/shipments/batch/{batchId}/status](https://docs.sendpro360.pitneycloud.com/openapi/batchshipping/batch-shipment/getbatchstatusapi.md): This operation retrieves the status of an existing Batch using Batch ID. Once the Job status is completed, the URL received from Response can be used to download the shipping label in PDF format. ### Get Batch Shipment Details - [GET /api/v1/shipments/batch/{batchId}/shipments](https://docs.sendpro360.pitneycloud.com/openapi/batchshipping/batch-shipment/getshipmentdetailsforbatchapi.md): "This API operation provides the shipment details for those shipments which are SUCCESS or FAILED during batch processing at the following levels: - addressValidation - rating - labelGeneration, and - voidLabel Based on fields/data mentioned in Query Parameter, user can check shipment details for particular status at any levels. If no values are provided in the fields mentioned in Query Parameter, the default for each will be: - Page: 1 - Size: 20 - Status: SUCCESS/FAILED.