Cancel a Shipment
Cancel a shipment, cancel carrier selection, and/or void a label.
About shipment cancellation
Your organization may need to cancel a shipment that has already been created. The Shipium system supports cancellation of shipments by calling the endpoint in the following table, which assumes you're using one of the authentication mechanisms detailed in our authentication documentation.
API type | API endpoint |
---|---|
POST | https://api.shipium.com/api/v1/deliveryexperience/cancel |
Authentication for API Calls
In the cURL example 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.
In addition to using this endpoint to cancel a shipment, you can cancel carrier selection for a shipment and void a shipping label. As Shipium recommends, you can use a cascading cancel to conduct all needed cancellations at once. This document provides guidance for how to do so.
The following table provides the request fields needed for calling this cancellation endpoint. While all fields are optional, one type of identifier must be included. However, only one of the unique IDs should be provided. If more than one of the IDs is included, the API call will result in an error.
Request field | Required/Optional | Field properties | Description |
---|---|---|---|
shipmentId | Optional | String | Unique ID of the shipment; either the shipiumShipmentId or the partnerShipmentId can be provided. Of the shipmentId , carrierSelectionId , shipiumLabelId , and carrierTrackingId , only one ID may be provided. |
carrierSelectionId | Optional | String | Unique ID of the carrier selection to be canceled; of the shipmentId , carrierSelectionId , shipiumLabelId , and carrierTrackingId , only one ID may be provided. |
shipiumLabelId | Optional | String | Unique Shipium ID of the label to be canceled and voided with the carrier; of the shipmentId , carrierSelectionId , shipiumLabelId , and carrierTrackingId , only one ID may be provided. |
carrierTrackingId | Optional | String | Carrier tracking ID of the label to be canceled and voided with the carrier; of the shipmentId , carrierSelectionId , shipiumLabelId , and carrierTrackingId , only one ID may be provided. |
cancellationDateTime | Optional | String ($date-time) Example: 2023-10-31T10:50:11.123456Z | Optional timestamp for when the entity/entities are canceled; this value defaults to now. |
cascadeCancel | Optional | BooleanTrue or False | An indicator to cascade the cancel down to any existing child entities. For example, if a shipmentId is passed, any associated carrier selection and label will also be canceled/voided. If a carrierSelectionId is passed, any associated label will also be canceled/voided. This value defaults to false . |
Cancel a shipment, cancel carrier selection, and/or void a label
Shipium recommends the use of a cascading cancel function to cancel a shipment, cancel its associated carrier selection, and void the label for the shipment. In a single call to the API endpoint, you can cancel all three, eliminating the need to first void any active label associated with the shipment (since the shipment can't be canceled if it has an active label).
No active labels
A shipment cannot be cancelled if it is associated with an active label.
If you would like to cancel a shipment and void the label, you can pass in an optional boolean parameter cascadeCancel
: "true". When the cascadeCancel
parameter is set to true
, a single call will cascade the cancel, and the single call will cancel the shipment, cancel any associated carrier selection, and void any associated label.
Example request for canceling a shipment and any associated carrier selection and label (recommended)
The following example uses the shipmentId
to cancel a shipment, cancel carrier selection, and void a shipment label. Only one of the unique IDs associated with your cancellation request can be included: either the shipmentId
, carrierSelectionId
, shipiumLabelId
, or carrierTrackingId
.
curl --request POST \
--url https://api.shipium.com/api/v1/deliveryexperience/cancel \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '{
"shipmentId": "myPartnerShipmentId",
"cascadeCancel": true,
"cancellationDateTime": "2024-08-21T18:30:55.558Z"
}'
Example request for canceling carrier selection and any associated label
The following example uses the carrierSelectionId
to cancel carrier selection and void a shipment label. Only one of the unique IDs associated with your cancellation request can be included: either the shipmentId
, carrierSelectionId
, shipiumLabelId
, or carrierTrackingId
.
curl --request POST \
--url https://api.shipium.com/api/v1/deliveryexperience/cancel \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '{
"carrierSelectionId": "911b488c-c620-4663-a554-bf9628e7ff43",
"cascadeCancel": true,
"cancellationDateTime": "2024-08-21T18:30:55.558Z"
}'
Example request for voiding a label
The following example uses the shipiumLabelId
to void a shipment label. Only one of the unique IDs associated with your cancellation request can be included: either the carrierSelectionId
or the shipiumLabelId
.
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"
}'
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