`cancelPickups()`

This method cancels one or more previously scheduled pickups. If your carrier allows previously scheduled pickups to be cancelled, you will need to implement this method.

Syntax

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

import {
  Transaction, PickupCancellation, PickupCancellationOutcome
} from "@shipengine/connect";
export default async function cancelPickups(
  transaction: Transaction,
  pickups: PickupCancellation[]
): Promise<void | PickupCancellationOutcome[]> {
  // Your code here
}

Parameters

`transaction`

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

`pickups`

An array of objects representing a request for a carrier to cancel one or more previously scheduled pickups.

Name	Type	Nullable?	Description
`cancellationID`	UUID		The unique ID of this cancellation. This ID is used to correlate cancellations with outcomes.
`id`	string		The unique ID of the pickup to be cancelled. This string will not contain newline characters.
`identifiers`	identifiers object		Your own identifiers for this pickup service.
`pickupService`	object		The pickup service to use for this pickup request.
`pickupService.id`	UUID		A UUID that uniquely identifies the pickup service. This ID should never change. This is the UUID you used in the Pickup Service Definition file for this pickup service.
`pickupService.identifiers`	identifiers object		Your own identifiers for this pickup service.
`pickupService.code`	string		Optional code used to map to what the carrier uses to identify the pickup service.
`pickupService.name`	string		The user-friendly service name (e.g. "One-Time Pickup", "Recurring Pickup", "Drop-Off"). This string will not contain newline characters.
`pickupService.description`	string		A short, user-friendly description of the service. This string will not contain newline characters.
`reason`	string		The reason for the cancellation. Valid values include the following: `not_ready` - The package was not ready for pickup. `price` - The customer cancelled the pickup because of the price. `schedule` - The pickup was cancelled because it could not be picked up within the needed time sframe. `carrier_failed_pickup` - The carrier failed to pick up the package. `other` - The cancellation is for a reason not covered by any of the other categories.
`notes`	object[]		An array of objects containing additional information about this cancellation.
`notes[].type`	notes type string		The type for this note.
`notes[].text`	string		The note text itself.
`address`	address object		The address where the package(s) should be picked up.
`contact`	contact info object		An object representing contact information about the person there to meet the driver.
`timeWindows`	object[]		A list of dates and times when the carrier intended to pickup. This array will contain at least one value.
`timeWindows[] .startDateTime`	date/time object	✔	The start date/time of the request window.
`timeWindows[].endDateTime`	date/time object	✔	The end date/time of the request window.
`timeWindows[].toString()`	method		A method that returns the time range as a string.
`shipments`	object[]		A list of shipments that were scheduled to be picked up. This array will contain at least one shipment.
`shipments.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 must not contain newline characters.
`shipments.identifiers`	identifiers object		Your own identifiers for this shipment.
`shipments[] .deliveryService`	delivery service object		The delivery service assigned to the original pickup request. This array will contain at least one value.
`shipments[].metadata`	object		The carrier's custom data about this shipment that was previously persisted by the ShipEngine Platform.
`shipments[].packages`	object[]		The list of packages in this shipment. This array will contain at least one value.
`shipments .packages[] .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 must not contain newline characters.
`shipments[] .packages[] .identifiers`	identifiers object		Your own identifiers for this package.
`shipments[] .packages[] .packaging`	object		The packaging used for this package.
`shipments[] .packages[] .packaging .id`	UUID		A UUID that uniquely identifies this packaging. This is the UUID you used int he Packaging Definition file for this packaging.
`shipments[] .packages[] .packaging .identifiers`	identifiers object		Your own identifiers for this packaging.
`shipments[] .packages[] .packaging[] .code`	string		Optional code used to map to what the carrier uses to identify the packaging.
`shipments[] .packages[] .dimensions`	object	✔	The dimensions for the package.
`shipments[] .packages[] .dimensions .length`	number		The length of the package. This value may contain decimals.
`shipments[] .packages[] .dimensions .width`	number		The width of the package. This value may contain decimals.
`shipments[] .packages[] .dimensions .height`	number		The height of this package. This value may contain decimals.
`shipments[] .packages[] .dimensions .unit`	string		The unit of measurement for the dimensions. Valid values include the following: `in` for inches `cm` for centimeters
`shipments[] .packages[] .weight`	object	✔	The weight of the package.
`shipments[] .packages[] .weight .value`	number		The weight value for this package. This value may contain decimals.
`shipments[] .packages[] .weight .unit`	string		The unit of measure for this weight. Valid values include the following: `g` for grams `oz` for ounces `kg` for kilograms `lb` for pounds
`shipments[] .packages[] .metadata`	object	✔	The carrier's custom data about this package that was previously persisted by ShipEngine Connect. Must be JSON serializable.
`shipments[].package`	object		The first package in the `packages` array. This is useful for carriers that only support single-piece shipments. This object has all the same properties as the objects in the `packages` array described above.

Return Value

`cancellationOutcomes`

An object that contains information about a pickup cancellation request.

Name	Type	Required?	Description
`cancellationId`	UUID	✔	An identifier that indicates which pickup cancellation this outcome is for.
`status`	string	✔	The status of the cancellation request. 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 for this cancellation request. 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 pickup. This string must not contain newline characters.
`notes`	object[]		An array of objects containing additional information about this cancellation.
`notes[].type`	notes type string	✔	The type for this note.
`notes[].text`	string	✔	The note text itself.
`metadata`	object		Custom data about this pickup that will be persisted by ShipEngine Connect. Must be JSON serializable.

Example

module.exports = async function cancelPickups(transaction, pickups) {
  let data = {
    operation: "pick_up_cancellation",
    scheduld_pick_ups: pickups.map((pickup) => {
      // STEP 1: Validation
      if (pickup.pickupService.id === sameDayPickup.id) {
        throw new Error(`Same-day pickups cannot be canceled`);
      }
      // STEP 2: Create the data that the carrier's API expects
      return {
        session_id: transaction.session.id,
        pick_up_id: pickup.id,
        service_code: pickup.pickupService.code,
        zone: Number.parseInt(pickup.address.postalCode),
        reference: pickup.reason,
      };
    })
  };
  // STEP 3: Call the carrier's API
  let response = await apiClient.request({ data });
  // STEP 4: Create the output data that ShipEngine expects
  return response.data.canceled_pick_ups.map((cancellation, index) => {
    if (cancellation.error) {
      return {
        cancellationID: pickups[index].cancellationID,
        confirmationNumber: cancellation.id,
        status: 'Error',
        notes: [
          {
            type: 'Internal',
            text: cancellation.reason,
          }
        ],
      };
    }
    else {
      return {
        cancellationID: pickups[index].cancellationID,
        confirmationNumber: cancellation.id,
        status: 'Success',
        notes: [
          {
            type: 'MessageToBuyer',
            text: `Pickup ${pickups[index].id} was canceled successfully`,
          }
        ],
      };
    }
  });
}

import {
  CancellationStatus,
  NoteType,
  PickupCancellation,
  PickupCancellationOutcome,
  Transaction
} from "@shipengine/connect";
export default async function cancelPickups(
  transaction: Transaction<Session>, pickups: PickupCancellation[]): Promise<PickupCancellationOutcome[]> {
  let data : PickUpCancellationRequest = {
    operation: "pick_up_cancellation",
    scheduld_pick_ups: pickups.map((pickup) => {
      // STEP 1: Validation
      if (pickup.pickupService.id === sameDayPickup.id) {
        throw new Error(`Same-day pickups cannot be canceled`);
      }
      // STEP 2: Create the data that the carrier's API expects
      return {
        session_id: transaction.session.id,
        pick_up_id: pickup.id,
        service_code: pickup.pickupService.code,
        zone: Number.parseInt(pickup.address.postalCode),
        reference: pickup.reason,
      };
    })
  };
  // STEP 3: Call the carrier's API
  let response = await apiClient.request<PickUpCancellationResponse>({ data });
  // STEP 4: Create the output data that ShipEngine expects
  return response.data.canceled_pick_ups.map((cancellation, index) => {
    if (cancellation.error) {
      return {
        cancellationID: pickups[index].cancellationID,
        confirmationNumber: cancellation.id,
        status: CancellationStatus.Error,
        notes: [
          {
            type: NoteType.Internal,
            text: cancellation.reason,
          }
        ],
      };
    }
    else {
      return {
        cancellationID: pickups[index].cancellationID,
        confirmationNumber: cancellation.id,
        status: CancellationStatus.Success,
        notes: [
          {
            type: NoteType.MessageToBuyer,
            text: `Pickup ${pickups[index].id} was canceled successfully`
          }
        ],
      };
    }
  });
}