Void a Shipment

HTTP Request

DELETE /v1/shipments/{shipmentId}


This operation cancels an unused shipment label and, for pre-paid labels, initiates a request for an electronic refund.

Note: In addition to this API, Pitney Bowes offers an Auto Refund service that automatically submits unused labels for electronic refund. For more information, see the Auto Refund FAQ. To enable the Auto Refund service for your account, please contact PB Support at ShippingAPISupport@pb.com.

See also: How do I request refund of a USPS pre-paid label?

Things to Consider


The following considerations apply to USPS shipments:

  1. All unused labels must be submitted for electronic refund within 30 days of printing.
  2. To view the status of the refund request, use the Transaction Reports API, which returns the refundStatus field.
  3. It can take up to 14 days for USPS to process and refund the value of the shipment label after submission.
  4. Approved postage refunds will be automatically credited to the payment account used to print the shipment label.
  5. You cannot request refunds for:
    • SBR labels (i.e., labels created with “shipmentType” set to “RETURN”). SBR labels do not incur charges unless they are used.
    • First-Class Mail letters and flats. Refunds for FCM letters and flats will be available in a future release.

Request URIs

Sandbox: https://api-sandbox.pitneybowes.com/shippingservices/v1/shipments/{shipmentId}
Production: https://api.pitneybowes.com/shippingservices/v1/shipments/{shipmentId}

Path Parameters

Name Description
shipmentId Required. The shipmentId returned by the original POST shipment request.

Request Headers

Name Description
Authorization Required. OAuth token generated using the Generate an OAuth Token API.
Content-Type Required. The media type of the request entity. Set this to application/json.

Required. A unique identifier for the transaction, up to 25 characters.

Important: You must ensure this is a unique id.

X-PB-UnifiedErrorStructure (new) Available in Sandbox: Set this to true to use the standard error object if an error occurs.

Request Elements

Name Data Type Description
carrier String

Required. Abbreviated name of the carrier. Valid values are:

  • USPS
cancelInitiator String Indicates that this refund request is initiated by the shipper. Set this to: SHIPPER

Response Elements

Name Data Type Description
carrier String

The abbreviated name of the carrier. Possible values are:

  • USPS
cancelInitiator String Indicates that the shipper initiated the refund. This is set to: SHIPPER
status String

Current status of the shipment refund. Automatically set to one of the following:

  • INITIATED (applies to USPS shipments)
  • APPROVED (applies to Newgistics shipments)
totalCarrierCharge BigDecimal USPS Only. The amount payable to the carrier for the original shipment..
parcelTrackingNumber String USPS Only. The tracking number of the original shipment.

Sample Request

curl -X DELETE .../v1/shipments/USPS2200116649182781 \
-H "Authorization: Bearer N7WPfrO0AfgDWXuKRTDlxpOKY3sG" \
-H "Content-Type: application/json"  \
-H "X-PB-TransactionId: 252d8bac-7520-4209-bff6-97b7" \
-H "X-PB-UnifiedErrorStructure: true"  \
-d '
    "carrier": "USPS",
    "cancelInitiator": "SHIPPER"

Sample Response

    "carrier": "USPS",
    "cancelInitiator": "SHIPPER",
    "totalCarrierCharge": 1.25,
    "parcelTrackingNumber": "9405512345641500057111",
    "status": "INITIATED"

Error Codes

For a list of all PB Complete Shipping APIs error codes, see Error Codes.