Skip to content
Shipping APIs
/
/
Cancel Shipment

Cancel Shipment

Request

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.
Security
bearerAuth
Headers
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 isn't 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".
X-PB-TransactionIdstring

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

Bodyapplication/jsonrequired
shipmentIdstring

The shipmentId is a unique identifier for an individual Shipment.

Example:"PUROLATOR2200626353009030"
parcelTrackingNumberstring

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

Example:"1234sjhgf"
referencesobject

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].

curl -i -X POST \
  https://api-sandbox.sendpro360.pitneybowes.com/shipping/api/v2/shipments/cancel \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'X-PB-Developer-Partner-Id: string' \
  -H 'X-PB-LocationId: string' \
  -H 'X-PB-TransactionId: string' \
  -d '{
    "shipmentId": "PUROLATOR2200626353009030",
    "parcelTrackingNumber": "1234sjhgf",
    "references": {
      "additionalReference1": "612987641",
      "additionalReference2": "989"
    }
  }'

Responses

The Shipment has been cancelled.

Bodyapplication/json
carrierstring

The name of the Carrier.

Example:"USPS"
totalCarrierChargenumber

The total amount payable to the carrier, including special service fees, surcharges, and any international taxes and duties.

Example:0
parcelTrackingNumberstring

The Tracking number given to the Parcel for tracking purpose.

Example:"9471309105156000624885"
statusstring

Status of the Shipment.

Enum:"INITIATED""APPROVED"
Example:"INITIATED"
referencesobject

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.

Response
{
  "carrier": "USPS",
  "totalCarrierCharge": 0,
  "parcelTrackingNumber": "9471309105156000624885",
  "status": "INITIATED",
  "references": {
    "additionalReference1": "612987641",
    "additionalReference2": "989"
  }
}