`cancelShipments()`

This method cancels shipments, which may include voiding labels, refunding charges, invalidating tracking numbers, updating manifests, or anything else that needs to happen when a shipment is canceled.

Most carrier applications should implement this method, unless you don't allow shipments to be canceled or voided after creation.

Syntax

module.exports = async function cancelShipments(transaction, shipments) {
  // Your code here
}

import {
  Transaction, ShipmentCancellation, ShipmentCancellationOutcome
} from "@shipengine/connect";
export default async function cancelShipments(
  transaction: Transaction,
  shipments: ShipmentCancellation[]
): Promise<void | ShipmentCancellationOutcome[]> {
  // Your code here
}

Parameters

`transaction`

A transaction object containing information about the transaction and session state.

`shipments[]`

An array of objects that indicate which shipments to cancel. This array will always contain at least one object.

Each object has the trackingNumber and identifiers of the shipment being canceled. It also has a cancellationID property, which is the ID of the cancellation request. You'll use this cancellationID to return the outcome of each cancellation, such as whether it was successful, failed, or could not be completed.

Name	Type	Description
`cancellationID`	UUID	The unique ID of this cancellation. This ID is used to correlate cancellations with outcomes.
`trackingNumber`	string	The master tracking number for the entire shipment. For single-piece shipments, this will be the same as the package tracking number. For multi-piece shipments, this may be a separate tracking number, or the same tracking number as one of the packages. This string will not contain newline characters.
`identifiers`	identifiers object	Your own identifiers for this shipment cancellation.
`metadata`	object	Custom data about this shipment that was persisted by ShipEngine Connect when this shipment was created. Must be JSON serializable.

Return Value

`cancellationOutcomes`

An array of objects that indicate the outcome of cancelling the shipments. This array will always contain at least one object. You may also choose not to return a value from this method.

Name	Type	Required?	Description
`cancellationID`	UUID	✔	The unique ID of this cancellation. This ID is used to correlate the outcome to the cancellation request.
`status`	string	✔	The status of the cancellation. Valid values include the following: `success` - Cancellation was successful. `error` - Cancellation encountered an error. `timeout` - Cancellation call timed out, probably related to a network error. `skipped` - Cancellation was skipped. `throttled` - Cancellation could not be made because requests are being throttled.
`confirmationNumber`	string		The confirmation number of the cancellation. This string must not contain newline characters.
`code`	string		The carrier's code for this cancellation outcome. This string must not contain newline characters.
`description`	string		The carrier's description of the cancellation outcome. This description should not be specific to this particular shipment. This string must not contain newline characters.
`notes`	object[]		An array of objects containing additional information about this shipment.
`notes[].type`	notes type string	✔	The type for this note.
`notes[].text`	string	✔	The note text itself.
`metadata`	object		Custom data about this shipment that was persisted by ShipEngine Connect. Must be JSON serializable.

Example

module.exports = async function cancelShipments(transaction, shipmentCancellations) {
  // STEP 1: Validation
  // STEP 2: Create the data that the carrier's API expects
  let data = {
    operation: "void_labels",
    session_id: transaction.session.id,
    cancellations: shipmentCancellations.map((cancellation) => {
      const { cancellationID, trackingNumber } = cancellation;
      return {
        cancellationID: cancellationID,
        internalReferenceID: cancellation.identifiers.internalReferenceID,
        trackingNumber: trackingNumber,
      };
    }),
  };
  // STEP 3: Call the carrier's API
  const response = await apiClient.request({ data });
  // STEP 4: Create the output data that ShipEngine expects
  return await formatCancellationResponse(response.data);
}

import {
  Transaction,
  ShipmentCancellation,
  ShipmentCancellationOutcome
} from "@shipengine/connect";
export default async function cancelShipments(
  transaction: Transaction, shipmentCancellations: ShipmentCancellation[]): Promise<void | ShipmentCancellationOutcome> {
  // STEP 1: Validation
  // STEP 2: Create the data that the carrier's API expects
  let data = {
    operation: "void_labels",
    session_id: transaction.session.id,
    cancellations: shipmentCancellations.map((cancellation) => {
      const { cancellationID, trackingNumber } = cancellation;
      return {
        cancellationID: cancellationID,
        internalReferenceID: cancellation.identifiers.internalReferenceID,
        trackingNumber: trackingNumber,
      };
    }),
  };
  // STEP 3: Call the carrier's API
  const response = await apiClient.request({ data });
  // STEP 4: Create the output data that ShipEngine expects
  return await formatCancellationResponse(response.data);
}