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.

NameTypeNullable?Description
pickupServiceobject

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.codestring

Optional code used to map to what the carrier uses to identify the pickup service.

pickupService.namestring

The user-friendly service name (e.g. "One-Time Pickup", "Recurring Pickup", "Drop-Off"). This string will not contain newline characters.

pickupService.descriptionstring

A short, user-friendly description of the service. This string will not contain newline characters.

timeWindowobject

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.

notesobject[]

An array of objects containing additional information about this pickup request.

notes[].type

notes type string

The type for this note.

notes[].textstring

The note text itself.

shipmentsobject[]

A list of shipments that should be scheduled for pickup. This array will contain at least one shipment.

shipments[]   .trackingNumberstring

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[].metadataobject

Custom data about this shipment that was previously persisted by the ShipEngine Platform.

shipments[].packagesobject[]

The list of packages in this shipment. This array will contain at least one value.

shipments   .packages[]   .trackingNumberstring

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[]   .packagingobject

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[]   .codestring

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[]   .dimensionsobject

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   .lengthnumber

The length of the package. This value may contain decimals.

shipments[]   .packages[]   .dimensions   .widthnumber

The width of the package. This value may contain decimals.

shipments[]   .packages[]   .dimensions   .heightnumber

The height of this package. This value may contain decimals.

shipments[]   .packages[]   .dimensions   .unitstring

The unit of measurement for the dimensions. Valid values include the following:

  • in for inches
  • cm for centimeters
shipments[]   .packages[]   .weightobject

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   .valuenumber

The weight value for this package. This value will not contain decimals.

shipments[]   .packages[]   .weight   .unitstring

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[]   .metadataobject

Custom data about this package that was persisted by ShipEngine Connect. Must be JSON serializable.

shipments[].packageobject

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.

NameTypeRequired?Description
idstring

The unique ID for this pickup. This string will not contain newline characters.

identifiers

identifiers object

Your own identifiers for this pickup.

timeWindowsobject[]

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".

shipmentsobject[]

The list of shipments to be picked-up. If not specified, the assumption is that all of the shipments will be picked up.

shipments[]   .trackingNumberstring

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.

notesobject[]

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[].textstring

The note text itself.

metadataobject

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);
}