Guides

Void a Label

Void a shipment label.

Suggest Edits

About label voiding

Your organization may find that you need to void a label because it will not be used. In this case, you can call the cancellation API endpoint to void a shipment label.

For most carriers, this should reverse any charges and make the label ineligible for use. However, there are exceptions and you should verify details of any particular carrier.

👉

Void is idempotent

If you make a call to void a label that has already been voided, you will receive a 200 response as your action (voiding a particular label) has already succeeded.

📘

Authentication for API calls

In the cURL examples on this page, the environment variable AUTHSTRING is used to handle authorization. The recipe below shows how to set it correctly for both API Key and OAuth users.

🔐
Authenticating for Curl
Open Recipe

Void a label

If you also need to cancel a shipment and/or carrier selection, Shipium recommends following the steps in Cancel a Shipment.

To simply void a label, you can call the cancellation endpoint with either a shipiumLabelId or a carrierTrackingId, which you should have based on prior calls, whether you used the Shipment Label API endpoint or the Carrier and Method Selection & Shipment Label API endpoint:

  • carrierTrackingId. The carrier tracking ID of the label to be canceled and voided with the carrier
  • shipiumLabelId. The unique Shipium ID of the label to be canceled and voided with the carrier

You also can include the cancellationDateTime, an optional timestamp for when the entity is canceled. This value defaults to now.

curl --request POST \
     --url https://api.shipium.com/api/v1/deliveryexperience/cancel \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{
        "shipiumLabelId": "198edb20-1076-42d8-8723-830dd6f27ef4",
        "cancellationDateTime": "2024-08-21T18:30:55.558Z"
      }'

Void a label with label ID

If you are only storing label IDs as part of your integration with Shipium, you may want to void a label without tracking order or shipment details. In this case, you can use the following call using only the label ID:

curl --request POST \
  --url  <<api_url>>/api/v1/deliveryexperience/shipment/carrierselection/voidlabel \
  --header $AUTHSTRING \
  --header 'accept: application/json' \
  --header 'content-type: application/json'
  --data '{"shipiumLabelId": "1234-5678-9012"}'

Void a previously generated label

To void a previously generated shipment label, follow the guidance in the API reference document.

📘

More information on the API responses

As with all Shipium API responses, this API follows the API Response Codes standards unless otherwise specified.

Resources

Your Shipium team member is available to help along the way. However, you might find these resources helpful:

Updated 8 months ago