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.
Updated about 2 months ago