Void Batch Shipping Labels

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.
SecuritybearerAuth
Request
path Parameters
batchId
required
string

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

header Parameters
X-PB-Developer-Partner-ID
string

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.

Request Body schema: application/json

This is the request body for cancelling the selected shipments or entire Batch of shipments*.

name
required
string

Indicates the name of the Batch, i.e., a list of shipments, which need to be cancelled.

reason
string

Reason to cancel the batch of shipments.

shipmentIds
Array of strings
  • Shipment ID is a unique identifier for an individual shipment. If ShipmentID(s) are passed in the array, then corresponding shipments will be cancelled. If ShipmentID(s) is/are not provided, then the entire shipments of the Batch will be cancelled.
Responses
200

The indicated shipment(s) of Batch have been successfully cancelled.

400

Invalid request.

401

The request could not be authorized.

404

The requested resource was not found.

500

The request could not be completed due to an internal server error.

post/api/v1/shipments/batch/{batchId}/void
Request samples
application/json
{
  • "name": "batchTest",
  • "reason": "Not processing due to rating issue.",
  • "shipmentIds": [
    ]
}
Response samples
application/json
{
  • "batchID": "p1B9VZYVp5V",
  • "status": "RATE_VALIDATION_FAILED"
}