Void a Shipment

HTTP Request

DELETE /v1/shipments/{shipmentId}

Summary

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 for unused USPS labels. The service 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

USPS (U.S. Postal Service)

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:
    • USPS 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.

UPS (United Parcel Service)

The following considerations apply to UPS® shipments:

  • UPS is a post-paid label.
  • If a shipment is voided, tear up the label. If a voided label is shipped, you will get billed for the label.
  • If you don’t use a label, make sure to use this operation to void the label. It is possible to still get billed for an unshipped label.

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.
X-PB-TransactionId

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

Important: You must ensure this is a unique id.

X-PB-Shipper-Carrier-AccountId UPS Only. The unique identifier returned in the shipperCarrierAccountId field by the Register an Existing Carrier Account API.
X-PB-UnifiedErrorStructure
Recommended. 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
  • NEWGISTICS
  • UPS
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
  • NEWGISTICS
  • UPS
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 Requests and Responses

See the following examples:

USPS 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"
}'

USPS Sample Response

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

Newgistics Sample Request

curl -X DELETE .../v1/shipments/NEWGISTICS2200162839557581 \
-H "Authorization: Bearer N7WPfrO0AfgDWXuKRTDlxpOKY3sG" \
-H "Content-Type: application/json"  \
-H "X-PB-TransactionId: a2b947-05897b2d-250f62f-1234" \
-H "X-PB-UnifiedErrorStructure: true"  \
-d '
{
    "carrier": "NEWGISTICS",
    "cancelInitiator": "SHIPPER"
}'

Newgistics Sample Response

{
    "carrier": "NEWGISTICS",
    "cancelInitiator": "SHIPPER",
    "status": "APPROVED"
}

UPS Sample Request

curl -X DELETE .../v1/shipments/UPS2200167630036174 \
-H "Authorization: Bearer N7WPfrO0AfgDWXuKRTDlxpOKY3sG" \
-H "Content-Type: application/json"  \
-H "X-PB-Shipper-Carrier-AccountId: <unique_carrier_id>" \
-H "X-PB-UnifiedErrorStructure: true"  \
-d '
{
    "carrier": "UPS",
    "cancelInitiator": "SHIPPER"
}'

UPS Sample Response

{
    "carrier": "UPS",
    "cancelInitiator": "SHIPPER",
    "totalCarrierCharge": 109.14,
    "parcelTrackingNumber": "1ZV69W421598241245",
    "status": "APPROVED"
}

Error Codes

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