Void a Shipment

HTTP Request

DELETE /v1/shipments/{shipmentId}?carrier={carrier}&cancelInitiator=SHIPPER

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. You cannot request refunds for:

    • Return labels
    • USPS First-Class Mail letters and flats
  2. If you do not use a post-paid label, void the label to ensure you are not billed and to provide the carrier an accurate count for any packages scheduled for pickup. When you void a post-paid label, tear up the label. If a voided label is shipped, you will be billed for the label.

  3. 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 Get 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

    You cannot request refunds for First-Class Mail letters and flats.

    Important

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

  4. CBDS: The following considerations are specific to the PB Cross-Border Delivery Service:

    • If the merchant’s delivery solution uses the Create Shipment API to print a label, then an unused label must be submitted for electronic refund within 25 days of printing.
    • If a CBDS shipment is voided after the parcel actually ships, Pitney Bowes returns the parcel and issues a return charge.
  5. UPS: The Void operation works only in Production.

    Note

    For UPS, the Void operation is not available in Sandbox.

Request URIs

Sandbox: https://api-sandbox.pitneybowes.com/shippingservices/v1/shipments/{shipmentId}?carrier={carrier}&cancelInitiator=SHIPPER
Production: https://api.pitneybowes.com/shippingservices/v1/shipments/{shipmentId}?carrier={carrier}&cancelInitiator=SHIPPER

See also APAC Services URIs.

APAC Services URIs

To void PB Standard Delivery shipments created with APAC Services, use the following URIs. You can use these URIs only if the shipment was created using APAC Services. These URIs apply only to PB Standard Delivery shipments created with 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 Parameters

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

Required. The carrier. Valid values are:

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.

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?cancelInitiator=SHIPPER \
-H "Authorization: Bearer <oauth_token>" \
-H "Content-Type: application/json" \
-H "X-PB-TransactionId: <unique_id>" \
-H "X-PB-UnifiedErrorStructure: true"
USPS Sample Void Response
{
    "cancelInitiator": "SHIPPER",
    "carrier": "USPS",
    "parcelTrackingNumber": "9405512345641500057111",
    "status": "INITIATED",
    "totalCarrierCharge": 1.25
}

PB Standard Delivery Void Shipment Example

PB Standard Delivery, Sample Void Request
curl -X DELETE .../v1/shipments/NGST2200247934278484?carrier=NEWGISTICS&cancelInitiator=SHIPPER \
-H "Authorization: Bearer <oauth_token>" \
-H "Content-Type: application/json" \
-H "X-PB-TransactionId: <unique_id>" \
-H "X-PB-UnifiedErrorStructure: true"
PB Standard Delivery, 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&cancelInitiator=SHIPPER \
-H "Authorization: Bearer <oauth_token>" \
-H "Content-Type: application/json" \
-H "X-PB-TransactionId: <unique_id>" \
-H "X-PB-UnifiedErrorStructure: true"
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?carrier=FEDEX&cancelInitiator=SHIPPER \
-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"
FedEx Sample Void Response
{
    "cancelInitiator": "SHIPPER",
    "carrier": "FEDEX",
    "parcelTrackingNumber": "794673546206",
    "status": "APPROVED",
    "totalCarrierCharge": 31.92
}

UPS Void Shipment Example

Note

The Void operation for UPS is available only in Production.

UPS Sample Void Request
curl -X DELETE .../v1/shipments/UPS2200167630036174?carrier=UPS&cancelInitiator=SHIPPER \
-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"
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.