Schedule Pickup

Instructions

Implementation Reference

• src/tools/pickup.ts:35-87 (handler)

  The async handler function for 'schedule_pickup'. It constructs the PickupCreationRequest payload (with shipper account, pickup date/time, address, package pieces, total weight, and payment method), POSTs it to the UPS pickup creation API, and returns the formatted response.

  async (params) => {
  	const accountNumber = client.getAccountNumber();
  
  	const pickupRequest = {
  		PickupCreationRequest: {
  			RatePickupIndicator: PICKUP.RATE_INDICATOR_YES,
  			Shipper: {
  				Account: {
  					AccountNumber: accountNumber ?? '',
  					AccountCountryCode: params.countryCode,
  				},
  			},
  			PickupDateInfo: {
  				CloseTime: params.closeTime,
  				ReadyTime: params.readyTime,
  				PickupDate: params.pickupDate,
  			},
  			PickupAddress: {
  				CompanyName: params.name,
  				ContactName: params.name,
  				AddressLine: [params.addressLine1, params.addressLine2].filter(Boolean),
  				City: params.city,
  				StateProvince: params.stateProvinceCode,
  				PostalCode: params.postalCode,
  				CountryCode: params.countryCode,
  				Phone: { Number: params.phone },
  			},
  			AlternateAddressIndicator: PICKUP.ALTERNATE_ADDRESS_YES,
  			PickupPiece: [
  				{
  					ServiceCode: params.serviceCode,
  					Quantity: String(params.packageCount),
  					DestinationCountryCode: params.countryCode,
  					ContainerCode: PICKUP.CONTAINER_PACKAGE,
  				},
  			],
  			TotalWeight: {
  				Weight: String(params.totalWeight),
  				UnitOfMeasurement: UNITS.WEIGHT_LBS,
  			},
  			OverweightIndicator: PICKUP.OVERWEIGHT_NO,
  			PaymentMethod: PICKUP.PAYMENT_ACCOUNT,
  			SpecialInstruction: params.specialInstructions ?? '',
  		},
  	};
  
  	const response = await client.post<unknown>(
  		`/api/pickupcreation/${API_VERSIONS.PICKUP}/pickup`,
  		pickupRequest,
  	);
  
  	return formatToolResponse(response);
  },

• src/tools/pickup.ts:10-33 (schema)

  The Zod-based input schema for 'schedule_pickup' defining all required/optional fields: pickupDate, readyTime, closeTime, name, phone, addressLine1/2, city, stateProvinceCode, postalCode, countryCode, packageCount, totalWeight, serviceCode, and specialInstructions.

  {
  	title: 'Schedule Pickup',
  	description:
  		'Schedule a UPS package pickup at a specific address and time. Provide the pickup date, time window, address, and package details. Returns a confirmation number to reference or cancel the pickup.',
  	inputSchema: {
  		pickupDate: z.string().describe('Pickup date in YYYYMMDD format'),
  		readyTime: z.string().describe('Earliest pickup time in HHmm format (e.g. "0900")'),
  		closeTime: z.string().describe('Latest pickup time in HHmm format (e.g. "1700")'),
  		name: z.string().describe('Contact name at pickup location'),
  		phone: z.string().describe('Contact phone number'),
  		addressLine1: z.string().describe('Pickup street address'),
  		addressLine2: z.string().optional().describe('Address line 2'),
  		city: z.string().describe('City'),
  		stateProvinceCode: z.string().describe('State/province code'),
  		postalCode: z.string().describe('ZIP/postal code'),
  		countryCode: z.string().length(2).default('US').describe('Country code'),
  		packageCount: z.number().int().positive().describe('Number of packages'),
  		totalWeight: z.number().positive().describe('Total weight in lbs'),
  		serviceCode: z
  			.string()
  			.default(PICKUP.SERVICE_ON_CALL_AIR)
  			.describe('Pickup service code (003=On Call Air, 001=Daily)'),
  		specialInstructions: z.string().optional().describe('Special instructions for driver'),
  	},

• src/tools/pickup.ts:8-9 (registration)

  Registration of the 'schedule_pickup' tool via server.registerTool('schedule_pickup', ...) inside the addPickupTools function.

  server.registerTool(
  	'schedule_pickup',

• src/server.ts:28-28 (registration)

  Top-level registration call where addPickupTools(server, client) is invoked from createServer() to register all pickup tools including 'schedule_pickup'.

  addPickupTools(server, client);

• src/types/pickup.ts:12-25 (schema)

  The SchedulePickupParams TypeScript interface defining the type structure for pickup scheduling parameters (used for type-checking, though the actual tool uses inline Zod schema).

  export interface SchedulePickupParams {
  	readonly pickupDate: string;
  	readonly readyTime: string;
  	readonly closeTime: string;
  	readonly address: PickupAddress;
  	readonly packages: readonly PickupPackage[];
  	readonly totalWeight: number;
  	readonly weightUnit?: 'LBS' | 'KGS';
  	readonly serviceCode?: PickupServiceCode;
  	readonly overweightIndicator?: boolean;
  	readonly paymentMethod?: 'account' | 'tracking';
  	readonly specialInstructions?: string;
  	readonly referenceNumber?: string;
  }