# Batch Shipment APIs

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

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

 - [Batch Shipment APIs](https://docs.shipping360.pitneybowes.com/_bundle/openapi/batchshipping.yaml)

## Batch Shipment

 - [POST /api/v1/bulkShipments](https://docs.shipping360.pitneybowes.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: S
 - [POST /api/v1/err/bulkShipments](https://docs.shipping360.pitneybowes.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. <br /> It provides the following inf
 - [POST /api/v1/shipments/importUrl](https://docs.shipping360.pitneybowes.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 shipmen
 - [POST /api/v1/err/shipments/importUrl](https://docs.shipping360.pitneybowes.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 f
 - [POST /api/v1/shipments/batch/{batchId}/process](https://docs.shipping360.pitneybowes.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 loca
 - [POST /api/v1/shipments/batch/{batchId}/void](https://docs.shipping360.pitneybowes.com/openapi/batchshipping/batch-shipment/voidshippinglabel.md): This operation cancels (voids) shipments which are created using the Batch API operation `createBulkShipments`. <br /> If user wants to cancel specific shipment(s) of the Batch, then s/he needs to pas
 - [GET /api/v1/shipments/batch/{batchId}/status](https://docs.shipping360.pitneybowes.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 /api/v1/shipments/batch/{batchId}/shipments](https://docs.shipping360.pitneybowes.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 -