Void a Shipment

HTTP Request

DELETE /v1/shipments/{shipmentId}

Summary

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

Important

USPS considers it a federal offense to induct a label that has already been refunded.

See also: How do I request a refund for a USPS prepaid label?

Things to Consider

See the considerations for the type of label you will void:

USPS Label

The following considerations apply when voiding a USPS® label:

  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:

UPS Label

The following considerations apply when voiding a UPS® label:

  • 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 URI: https://api-sandbox.pitneybowes.com/shippingservices/v1/shipments/{shipmentId}
Production URI: https://api.pitneybowes.com/shippingservices/v1/shipments/{shipmentId}

Request URIs for APAC (Newgistics Only)

For Newgistics requests that originate in the Asia-Pacific (APAC) region, Pitney Bowes provides regional URIs to optimize performance. You can use an APAC URI only if the Newgistics shipment was created using an APAC URI. When using the URI, you must set the carrier query parameter to Newgistics:

Sandbox URI for APAC: https://apac-sandbox.shippingapi.pitneybowes.com/shippingservices/v1/shipments/{shipmentId}?carrier=Newgistics
Production URI for APAC: https://apac.shippingapi.pitneybowes.com/shippingservices/v1/shipments/{shipmentId}?carrier=Newgistics

Path Parameter

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

Query Parameter

Name Description
carrier Applies to requests from the Asia-Pacific region. If your request originates in the Asia-Pacific Region and if you use the APAC URIs, you must set carrier query parameter to Newgistics.

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

Conditional. Abbreviated name of the carrier. This is required if the carrier is not USPS. Valid values are:

  • USPS (default)
  • 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

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 Shipping APIs error codes, please see Error Codes.