Cancel Shipment

This operation cancels or voids a shipment label that has not been processed by the carrier. When you cancel an unused prepaid shipment label, the API initiates a request for an electronic refund.

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.
  • USPS:
    • Cancel unused USPS prepaid labels within 30 days of printing to start the refund process.
    • Refund requests are processed within 14 business days from the date the refund was requested, provided the label has not been used.
    • Approved refunds are automatically credited to the account you used to pay for the label.
    • Note: USPS considers it a federal offense to induct a label that has already been refunded.
    • Note: Refunds are not available for First-Class Mail letters and flats.
    • Note: Refunds are subject to the policies of the applicable carrier.
  • 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.
SecuritybearerAuth
Request
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 isn't required.

X-PB-LocationId
string

This is the Location ID assigned as per the Developer's and Partner's parsed locations, to which all transactions will be billed.
Partner's location will be used for billing if it is configured, however, in case Partner's location is not given, then the Developer's location will be taken. Developer's location will be the default value.
Additionally, Developers and Partners can use carriers belong to this location only.

X-PB-TransactionId
string

A unique Transaction ID provided by the partner which is used to enable debugging and linking between the client's transaction and the system.

Request Body schema: application/json
shipmentId
required
string

The shipmentId is a unique identifier for an individual Shipment.

parcelTrackingNumber
string

The tracking number associated with one parcel in a shipment. The parcel tracking number can be used to track one specific parcel.

object

Contains key value map for passing references which is printed on Shipping Label.
For example Department Name, Invoice No., PO No., Package description, Order No./ Purchase Order No., Carrier note, Cost Account No., Transportation No., etc. . Max references allowed here is 2, and max length of each Reference field is 30. [IN/OUT].

Responses
200

The Shipment has been 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 error.

post/api/v2/shipments/cancel
Request samples
application/json
{
  • "shipmentId": "PUROLATOR2200626353009030",
  • "parcelTrackingNumber": "1234sjhgf",
  • "references": {
    }
}
Response samples
application/json
{
  • "carrier": "USPS",
  • "totalCarrierCharge": 0,
  • "parcelTrackingNumber": "9471309105156000624885",
  • "status": "INITIATED",
  • "references": {
    }
}