`schedulePickup()`

This method schedules a package pickup for a particular time and place. It should be implemented by most carrier apps, unless the carrier does not support scheduled package pickups.

Syntax

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

import { Transaction, PickupRequest, PickupConfirmation } from "@shipengine/connect";
export default async function schedulePickup(
  transaction: Transaction,
  pickup: PickupRequest
): Promise<PickupConfirmation> {
  // Your code here
}

Parameters

`transaction`

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

`pickup`

An object representing a request for a carrier to pickup one or more packages at a particular time and place.

Name	Type	Nullable?	Description
`pickupService`	object		The pickup service to use for this pickup request.
`pickupService.id`	UUID		A UUID that uniquely identifies the pickup service. 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.
`timeWindow`	object		The requested window of time for the carrier to arrive.
`timeWindow.startDateTime`	date/time object	✔	The start date/time of the request window.
`timeWindow.endDateTime`	date/time object	✔	The end date/time of the request window.
`timeWindow.toString()`	method		Returns the time range as a string.
`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.
`notes`	object[]		An array of objects containing additional information about this pickup request.
`notes[].type`	notes type string		The type for this note.
`notes[].text`	string		The note text itself.
`shipments`	object[]		A list of shipments that should be scheduled for pickup. 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 will not contain newline characters.
`shipments[].identifiers`	identifiers object		Your own identifiers for this shipment.
`shipments[] .deliveryService`	delivery service object		The delivery service assigned to this shipment.
`shipments[].metadata`	object		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 will not contain newline characers.
`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 in the Packaging Definition file for this packaging type.
`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. The value `custom` indicates user-defined packaging. Some of our products allow users to enter custom packaging instead of one of your app's pre-defined packaging types.
`shipments[] .packages[] .dimensions`	object	✔	The dimensions for the package. This property is not required. If it is provided, it must contain all of its required properties, listed below.
`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. This property is not required. If it is provided, it must contain all of its required properties, listed below.
`shipments[] .packages[] .weight .value`	number		The weight value for this package. This value will not 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	✔	Custom data about this package that was 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

`confirmation`

An object that contains confirmation that a package has been scheduled for pickup.

Name	Type	Required?	Description
`id`	string	✔	The unique ID for this pickup. This string will not contain newline characters.
`identifiers`	identifiers object		Your own identifiers for this pickup.
`timeWindows`	object[]	✔	A list of dates and times when the carrier intends to be available to pickup.
`timeWindows[] .startDateTime`	date/time object, or Date object object, or a string representing the date and time in ISO format.		The start date/time of the request window.
`timeWindows[].endDateTime`	date/time object, or Date object object, or a string representing the date and time in ISO format.		The end date/time of the request window.
`charges`	charge object[]	✔	The breakdown of charges for this shipment. If the carrier does not provide a detailed breakdown, then just use a single charge of type "shipping".
`shipments`	object[]		The list of shipments to be picked-up. If not specified, the assumption is that all of the shipments will be picked up.
`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.
`notes`	object[]		An array of objects containing additional information about this pickup request. This property is not required. If it is provided, it must contain all of its required properties, listed below.
`notes[].type`	notes type string	✔	The type for this note.
`notes[].text`	string	✔	The note text itself.
`metadata`	object		The carrier's custom data about this pickup that will be persisted by ShipEngine Connect. Must be JSON serializable.

Example

module.exports = async function schedulePickup(transaction, pickup) {
  // STEP 1: Validation
  // STEP 2: Create the data that the carrier's API expects
  let data = {
    operation: "pick_up",
    session_id: transaction.session.id,
    service_code: pickup.pickupService.code,
    date_time: pickup.timeWindow.startDateTime.toISOString(),
    zone: Number.parseInt(pickup.address.postalCode),
    contact_phone: pickup.contact.phoneNumber,
    total_weight: pickup.shipments.reduce((w, ship) => w + ship.package.weight.ounces, 0),
  };
  // STEP 3: Call the carrier's API
  const response = await apiClient.request({ data });
  // STEP 4: Create the output data that ShipEngine expects
  return formatConfirmation(response.data);
}

import {
  ChargeType,
  PickupConfirmation,
  PickupRequest,
  Transaction
} from "@shipengine/connect";
export default async function schedulePickup(
  transaction: Transaction<Session>, pickup: PickupRequest): Promise<PickupConfirmation> {
  // STEP 1: Validation
  // STEP 2: Create the data that the carrier's API expects
  let data: PickUpRequest = {
    operation: "pick_up",
    session_id: transaction.session.id,
    service_code: pickup.pickupService.code,
    date_time: pickup.timeWindow.startDateTime.toISOString(),
    zone: Number.parseInt(pickup.address.postalCode),
    contact_phone: pickup.contact.phoneNumber,
    total_weight: pickup.shipments.reduce((w, ship) => w + ship.package.weight.ounces, 0),
  };
  // STEP 3: Call the carrier's API
  const response = await apiClient.request<PickUpResponse>({ data });
  // STEP 4: Create the output data that ShipEngine expects
  return formatConfirmation(response.data);
}