Batch Shipment

Shipping APIs

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.

Operations

Create Bulk Shipments

Request

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.

Security

bearerAuth

X-PB-Developer-Partner-IDstring

The Developer-Partner-ID is assigned by PB to uniquely identify a developer's strategic business partners. If the developer is the sole business partner, this field is not required.

X-PB-LocationIdstring

The X-PB-LocationId header identifies the enterprise, developer, or partner location under which a shipment is processed and billed. If the header is not provided, the system defaults to the enterprise-level location that was created during developer account onboarding. This default location is automatically used for shipment processing and billing.

Requirement Rules

The X-PB-LocationId header is optional when the shipment origin country code matches the enterprise's default address country code.
The X-PB-LocationId header is required when the shipment origin country code differs from the enterprise's default address country code.
If the header is required but not provided, the API will return a validation error "invalid origin countryCode".

Bodyapplication/jsonrequired

This is the request body to create Bulk Shipment.

One of:

This ShipmentBatch contains the schema information.

namestringrequired

Name of the of Batch which consists of multiple shipments (shipments in bulk) for Label printing, e.g. Bulk07.

Example:"Bulk07"

groupNamestring

Indicates the name of the group of batches, which consists of multiple Batch groups.

Example:"Shipping-021"

sizestringrequired

This indicates the label size of the Bulk Shipment when it gets printed,i.e., DocSize. This has two options 8' X 11' or 4' X 6'.

Enum:"DOC_8X11""DOC_4X6"

Example:"DOC_8X11"

typestringrequired

Indicates the type of the Batch Shipment, e.g., Shipping Label.

Value:"SHIPPING_LABEL"

Example:"SHIPPING_LABEL"

formatstring

Defines the type of the shipment, which is printed, e.g., Shipping label gets printed in PDF form.

Value:"PDF"

Example:"PDF"

carrierAccountIdstringrequired

A unique identifier associated with the Carrier account used by client users during shipment process. Default CarrierAccountID for this batch will be user's registered carrier account. User can override this value by defining it at shipment level.

Example:"abcd123"

serviceIdstringrequired

A unique identifier given to the carrier-specific service, which varies as per carrier selection. User can override this value by defining it at Shipment level.

Example:"LIB"

parcelTypestringrequired

Parcel Type is required for creating a shipment while rating a parcel, which varies as per Carrier selection and selected services. Different carriers have different Services and associated ParcelTypes, e.g., FRPKG, LGENV, TUBE, and PKG.
User can override this value by defining it at Shipment level.

Example:"LP"

parcelIDstring

A unique identifier given to the parcel or package corresponding to the selected service. This is optional field, but is used in few cases. User can override this value by defining it at Shipment level.

Example:"PMB4"

specialServicesArray of objects(SpecialService)

It provides a carrier based special or extra service, which also varies as per selected service and parcel type. User can override this value by defining it at shipment level.

shipmentsArray of objects(Shipment)required

curl -i -X POST \
  https://api-sandbox.sendpro360.pitneybowes.com/shipping/api/v1/bulkShipments \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'X-PB-Developer-Partner-ID: string' \
  -H 'X-PB-LocationId: string' \
  -d '{
    "name": "Bulk07",
    "groupName": "Shipping-021",
    "size": "DOC_8X11",
    "type": "SHIPPING_LABEL",
    "format": "PDF",
    "carrierAccountId": "abcd123",
    "serviceId": "LIB",
    "parcelType": "LP",
    "parcelID": "PMB4",
    "specialServices": [
      {
        "inputParameters": [
          {
            "name": "INPUT_VALUE",
            "value": "100"
          }
        ],
        "specialserviceId": "Ins"
      }
    ],
    "shipments": [
      {
        "externalId": "string",
        "fromAddress": {
          "name": "Anupama",
          "addressLine1": "27 Watervw Dr",
          "addressLine2": "Street-257",
          "addressLine3": "Near XZ Tower",
          "cityTown": "Stamford",
          "stateProvince": "CT",
          "postalCode": 6905,
          "inductionPostalCode": "06905",
          "countryCode": "US",
          "company": "PB",
          "phone": "203-555-1213",
          "email": "anupama.k@gmail.com",
          "residential": true
        },
        "toAddress": {
          "name": "John Smith",
          "addressLine1": "98 Watervw Dr",
          "addressLine2": "Street-975",
          "addressLine3": "Near ABC Tower",
          "cityTown": "Shelton",
          "stateProvince": "CT",
          "postalCode": 6905,
          "countryCode": "US",
          "company": "PB",
          "phone": "203-555-1213",
          "email": "anupama.kr@gmail.com",
          "residential": true
        },
        "parcel": {
          "length": 2,
          "width": 1,
          "height": 1,
          "dimUnit": "IN",
          "weightUnit": "OZ",
          "weight": 2
        },
        "carrierAccountId": "asas2223",
        "parcelType": "PKG",
        "serviceId": "PM",
        "dateOfShipment": "2023-04-03",
        "specialServices": [
          {
            "inputParameters": [
              {
                "name": "INPUT_VALUE",
                "value": "100"
              }
            ],
            "specialserviceId": "Ins"
          }
        ],
        "shipmentOptions": {
          "addToManifest": true,
          "printCustomMessage": "Print Message 1",
          "receiptOption": "RECEIPT_WITH_INSTRUCTIONS",
          "printDepartment": "department",
          "printInvoiceNumber": "invoicenumber",
          "printPONumber": "ponumber",
          "minimalAddressValidation": true,
          "bookingConfirmationNumber": "XXXX56789812"
        },
        "metadata": [
          {
            "name": "PB-PUN-CostAccount",
            "value": "CostAccount-00PBPUN"
          }
        ],
        "additionalAddresses": [
          {
            "address": {
              "residential": false,
              "phone": "732-443-1007",
              "countryCode": "US",
              "postalCode": "08810-1411",
              "cityTown": "DAYTON",
              "name": "Warehouse Manager",
              "stateProvince": "NJ",
              "addressLine1": "2270 US HIGHWAY 130"
            },
            "addressType": "BROKER"
          }
        ],
        "altReturnAddress": {
          "addressLine1": "27 Waterview Dr",
          "addressLine2": "near abc street",
          "addressLine3": "near xyz street",
          "company": "PB",
          "email": "user@email.com",
          "residential": true,
          "cityTown": "Shelton",
          "countryCode": "US",
          "name": "User Name",
          "phone": "203-555-1213",
          "postalCode": "06484",
          "stateProvince": "CT"
        }
      }
    ]
  }'

Responses

The Bulk Shipment has been successfully created..

Bodyapplication/json

batchIdstring

This is a system-generated unique identifier assigned to the Batch while it is processed.

groupNamestring

Indicates the name of the group of batches, which consists of multiple Batch groups.

namestring

Name of the of Batch which consists of multiple shipments (shipments in bulk).

statusstring(JobStatus)

This shows all the status related to the Batch Job.

Enum:"SUBMITTED""ADDRESS_VALIDATION_PROCESSING""ADDRESS_VALIDATED""ADDRESS_VALIDATION_FAILED""RATE_VALIDATION_PROCESSING""RATE_VALIDATED""RATE_VALIDATION_FAILED""LABEL_GENERATION_PROCESSING""LABEL_GENERATION_FAILED""LABEL_GENERATED"

addressValidationobject(AddressCountStatus)

This indicates the processing status of address validation stage.

ratingobject(RatingCountStatus)

This indicates the processing status of rating stage.

labelGenerationobject(LabelGenerationCountStatus)

This indicates the processing status of label generation stage.

Response

{
  "batchId": "string",
  "groupName": "string",
  "name": "string",
  "status": "SUBMITTED",
  "addressValidation": {
    "success": 20,
    "failed": 10,
    "pending": 10
  },
  "rating": {
    "success": 20,
    "failed": 10,
    "pending": 10
  },
  "labelGeneration": {
    "success": 20,
    "failed": 10,
    "pending": 10
  }
}

Batch Shipment

Create Bulk Shipments

Request

Headers

Responses

Was this helpful?