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.

📘

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.

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:

• Terms and Definitions

• Troubleshooting Guide

• Contact Shipium Support