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 void API endpoint on a carrier label to void it.

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

The general form of the void call is shown below. It requires three pieces of information that 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. These elements are:

  • carrierTrackingId. The carrierSelectionId for the shipment and label in question
  • shipiumLabelId. The shipiumLabelId that you are trying to void
<<api_url>>/api/v1/deliveryexperience/shipment/{shipiumShipmentId}/carrierSelection/{carrierSelectionId}/label/{shipiumLabelId}/void

Example request

Let's assume that you had previously made a label call and it could be accessed using the following GET:

curl --request GET \
  --url  <<api_url>>/api/v1/deliveryexperience/shipment/a69be08c-f3f5-4c26-ab16-46cbfdf9004e/carrierselection/2dc48065-89cf-4cd2-88be-ba6c69b3768e/label/d838f2a6-4abd-499a-a5d1-186ea7f90184 \
  --header 'accept: application/json' \
  --header $AUTHSTRING \
  --header 'content-type: application/json'

You could void this label using the following void call:

curl --request POST \
  --url  <<api_url>>/api/v1/deliveryexperience/shipment/a69be08c-f3f5-4c26-ab16-46cbfdf9004e/carrierselection/2dc48065-89cf-4cd2-88be-ba6c69b3768e/label/d838f2a6-4abd-499a-a5d1-186ea7f90184/void \
  --header 'accept: application/json' \
  --header $AUTHSTRING \
  --header 'content-type: application/json'

Short form of void call

If you are only storing label IDs as part of your integration with Shipium, you may want to void the label without tracking order or shipment details. In this case, you can use the shortened version of the void 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 about 2 months ago