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?

Considerations

  1. You cannot request refunds for:

    • Returns labels

    • PB Expedited (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. PB Expedited (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 original Create Shipment request printed a label, the 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 URLs

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

See also APAC Services URLs.

APAC Services URLs

To void PB Delivery shipments created with APAC Services, use the following URLs. You can use these URLs only if the shipment was created using APAC Services. These URLs apply only to PB Delivery shipments created with APAC Services:

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

  • USPS: PB Expedited (default)

  • PBCS: PB Delivery

  • PBI: PB Cross-Border Delivery Service (CBDS)

  • FEDEX

  • UPS

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. The following characters are allowed: letters, numbers, hyphens (-), and underscores (_).

Important: Ensure this is a unique ID.

X-PB-Shipper-Carrier-AccountId

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

Required if the merchant has registered multiple accounts for the same carrier. For more information, see Add Commercial Carrier Accounts.

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:

  • USPS: PB Expedited (default)

  • PBCS: PB Delivery

  • PBI: PB Cross-Border Delivery Service (CBDS)

  • FEDEX

  • UPS

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:

PB Expedited Sample Void Shipment

Sample 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"
Sample Response
{
    "cancelInitiator": "SHIPPER",
    "carrier": "USPS",
    "parcelTrackingNumber": "9405512345641500057111",
    "status": "INITIATED",
    "totalCarrierCharge": 1.25
}

PB Delivery Sample Void Shipment

Sample Request
curl -X DELETE ".../v1/shipments/NGST2200247934278484?carrier=PBCS&cancelInitiator=SHIPPER" \
-H "Authorization: Bearer <oauth_token>" \
-H "Content-Type: application/json" \
-H "X-PB-TransactionId: <unique_id>" \
-H "X-PB-UnifiedErrorStructure: true"
Sample Response
{
    "cancelInitiator": "SHIPPER",
    "carrier": "PBCS",
    "status": "APPROVED"
}

CBDS Sample Void Shipment

Sample 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"
Sample Response
{
    "cancelInitiator": "SHIPPER",
    "carrier": "PBI",
    "parcelTrackingNumber": "UPPBX001513FC13FA1C1",
    "status": "INITIATED"
}

FedEx Sample Void Shipment

Sample 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"
Sample Response
{
    "cancelInitiator": "SHIPPER",
    "carrier": "FEDEX",
    "parcelTrackingNumber": "794673546206",
    "status": "APPROVED",
    "totalCarrierCharge": 31.92
}

UPS Sample Void Shipment

Note

The Void operation for UPS is available only in Production.

Sample 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"
Sample Response
{
    "cancelInitiator": "SHIPPER",
    "carrier": "UPS",
    "parcelTrackingNumber": "1ZV69W421598241245",
    "status": "APPROVED",
    "totalCarrierCharge": 109.14
}

Error Codes

For a list of all error codes returned by the Ecommerce APIs, please see Error Codes.