Void a Shipment

HTTP Request

DELETE /v1/shipments/{shipmentId}

Summary

This operation cancels an unused shipment label. When you cancel an unused prepaid shipment label, the API initiates a request for an electronic refund.

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

Things to Consider

  1. USPS: You must cancel an unused label within 30 days of printing. When you cancel an unused label, the API initiates a request for an electronic refund. USPS can take up to 14 days to process and refund the value of the shipment label after submission. To view the status of the refund request, use the Transaction Reports API, which returns the refundStatus field. Approved postage refunds will be automatically credited to the payment account used to print the shipment label.

    Important

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

  2. CBDS: The following considerations apply:

    • If the merchant uses the First-Mile Inclusive solution, an unused label must be submitted for electronic refund within 25 days of printing.
    • If a shipment is voided after the parcel actually ships, Pitney Bowes returns the parcel and issues a return charge.
  3. UPS: The Void operation does not work in the Sandbox environment. The Void operation works only in Production.

  4. If you don’t use a postpaid label, make sure to void the label. Voiding the label ensures that you are not billed for the unshipped label and provides the carrier an accurate count for packages scheduled for pickup. When you void a postpaid label, tear up the label. If a voided label is shipped, you will be billed for the label.

  5. You cannot request refunds for:

    • First-Class Mail letters and flats
    • Return labels

Request URIs

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

Note: Do not use the above URIs for shipments created with APAC Services. Instead, use the APAC Services URIs below.

URIs for APAC Services (PB Standard Only)

To void shipments created with APAC Services, you must use the following URIs. You can use these URIs only if a shipment was created using APAC Services.

Sandbox URI APAC: https://apac-sandbox.shippingapi.pitneybowes.com/shippingservices/v1/shipments/{shipmentId}?carrier=Newgistics
Production URI 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

APAC Services, CBDS. The carrier. This is required in the following cases:

  • If the shipment used PB Standard (formerly Newgistics) and the original shipment request used the APAC URI, then set this to Newgistics.
  • If the shipment used CBDS, set this to PBI.

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

Conditional. The unique identifier for the carrier account. To retrieve the identifier, see this FAQ.

This header is required if the merchant has registered multiple accounts for the same carrier. For more information, see Carrier Account Registration.

X-PB-UnifiedErrorStructure Recommended. Set this to true to use the standard error object if an error occurs.

Request Elements

Name Data Type Description
cancelInitiator String Indicates that this refund request is initiated by the shipper. Set this to: SHIPPER
carrier String

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

Response Elements

Name Data Type Description
cancelInitiator String Indicates that the shipper initiated the refund. This is set to: SHIPPER
carrier String

The abbreviated name of the carrier. Possible values are:

parcelTrackingNumber String The tracking number of the original shipment. This is returned for USPS, CBDS, FedEx, and UPS.
status String

Current status of the shipment refund. Possible values are:

  • INITIATED (Applies to prepaid labels only)
  • APPROVED
totalCarrierCharge BigDecimal The amount payable to the carrier for the original shipment. This is returned for USPS, FedEx, and UPS.

Sample Requests

See the following examples:

USPS Void Shipment Example

USPS Sample Void Request
curl -X DELETE .../v1/shipments/USPS2200116649182781 \
-H "Authorization: Bearer <oauth_token>" \
-H "Content-Type: application/json" \
-H "X-PB-TransactionId: <unique_id>" \
-H "X-PB-UnifiedErrorStructure: true" \
-d '
{
    "cancelInitiator": "SHIPPER",
    "carrier": "USPS"
}'
USPS Sample Void Response
{
    "cancelInitiator": "SHIPPER",
    "carrier": "USPS",
    "parcelTrackingNumber": "9405512345641500057111",
    "status": "INITIATED",
    "totalCarrierCharge": 1.25
}

PB Standard (Newgistics) Void Shipment Example

PB Standard Sample Void Request
curl -X DELETE .../v1/shipments/NEWGISTICS2200162839557581 \
-H "Authorization: Bearer <oauth_token>" \
-H "Content-Type: application/json" \
-H "X-PB-TransactionId: <unique_id>" \
-H "X-PB-UnifiedErrorStructure: true" \
-d '
{
    "cancelInitiator": "SHIPPER",
    "carrier": "NEWGISTICS"
}'
PB Standard Sample Void Response
{
    "cancelInitiator": "SHIPPER",
    "carrier": "NEWGISTICS",
    "status": "APPROVED"
}

CBDS Void Shipment Example

CBDS Sample Void Request
curl -X DELETE .../v1/shipments/UPPBX001513FC13FA1C1?carrier=PBI \
-H "Authorization: Bearer <oauth_token>" \
-H "Content-Type: application/json" \
-H "X-PB-TransactionId: <unique_id>" \
-H "X-PB-UnifiedErrorStructure: true" \
-d '
{
    "cancelInitiator": "SHIPPER",
    "carrier": "PBI"
}'
CBDS Sample Void Response
{
    "carrier": "PBI",
    "cancelInitiator": "SHIPPER",
    "parcelTrackingNumber": "UPPBX001513FC13FA1C1",
    "status": "INITIATED"
}

FedEx Void Shipment Example

FedEx Sample Void Request
curl -X DELETE .../v1/shipments/FEDEX2200287696529990 \
-H "Authorization: Bearer <oauth_token>" \
-H "Content-Type: application/json" \
-H "X-PB-TransactionId: <unique_id>" \
-H "X-PB-Shipper-Carrier-AccountId: <unique_carrier_account_id>" \
-H "X-PB-UnifiedErrorStructure: true" \
-d '
{
    "cancelInitiator": "SHIPPER",
    "carrier": "FEDEX"
}'
FedEx Sample Void Response
{
    "cancelInitiator": "SHIPPER",
    "carrier": "FEDEX",
    "parcelTrackingNumber": "794673546206",
    "status": "APPROVED",
    "totalCarrierCharge": 31.92
}

UPS Void Shipment Example

UPS Sample Void Request
curl -X DELETE .../v1/shipments/UPS2200167630036174 \
-H "Authorization: Bearer <oauth_token>" \
-H "Content-Type: application/json" \
-H "X-PB-TransactionId: <unique_id>" \
-H "X-PB-Shipper-Carrier-AccountId: <unique_carrier_account_id>" \
-H "X-PB-UnifiedErrorStructure: true" \
-d '
{
    "cancelInitiator": "SHIPPER",
    "carrier": "UPS"
}'
UPS Sample Void Response
{
    "cancelInitiator": "SHIPPER",
    "carrier": "UPS",
    "parcelTrackingNumber": "1ZV69W421598241245",
    "status": "APPROVED",
    "totalCarrierCharge": 109.14
}

Error Codes

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