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.

Shipment Cancelation Rules

  • Provide either shipmentId or parcelTrackingNumber to cancel a shipment.
  • If both are provided, shipmentId takes precedence and parcelTrackingNumber is ignored.
  • If only parcelTrackingNumber is provided, the shipment associated with that parcel tracking number is canceled.
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

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".
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
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": {
    }
}