Voiding a Specific Label

Overview

From time to time, you 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 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.

General form of void call

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 label-generation endpoint or mega-shipment-process endpoint. These elements are:

• carrierTrackingId - the carrierSelectionId for the shipment & 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

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. This is shown below:

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 returns the label that was voided

Void a previously generated shipment label.

📘

More information on the API responses

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