Schedule a Carrier Pickup with UPS, FedEx, DHL and USPS

A pickup request asks a carrier to send a driver to an address on a given day to collect packages you have already labelled. It is a separate API call from creating the label, and it is the step most integrations forget until a customer asks why nothing was collected.

In RocketShipIt every carrier books a pickup the same way — action is createpickup, the address goes in pickup_* parameters, and the response comes back as a confirmation number you must store:

{
  "carrier": "UPS-REST",
  "action": "createpickup",
  "params": {
    "key": "your-key-from-authenticate-request",
    "pickup_company_name": "Acme Inc",
    "pickup_contact_name": "Jane Doe",
    "pickup_addr1": "940 Presidio Ave",
    "pickup_city": "San Francisco",
    "pickup_state": "CA",
    "pickup_code": "94115",
    "pickup_country": "US",
    "pickup_phone": "123-123-1234",
    "pickup_location": "Front desk",
    "pickup_service_code": "002",
    "pickup_container_code": "01",
    "pickup_quantity": 1,
    "pickup_total_weight": 12,
    "weight_unit": "LBS",
    "pickup_date": "20260115",
    "ready_time": "0800",
    "close_time": "1700"
  }
}

{
  "pickup_id": "2929AONCALL",
  "location": "",
  "charge": 7.4,
  "errors": []
}

pickup_id is the value you need to cancel the pickup later. Store it against the shipment — every carrier refuses a cancel without it, and none of them will look it up from the address.

Do you need a pickup request at all?#

Only if you do not already have one. There are three ways packages leave a building and the API call is needed for exactly one of them:

An on-call pickup usually carries a fee, which is why the UPS and DHL calls can return a charge. A daily pickup is billed as a weekly service charge instead, and a drop-off is free. If you are integrating a high-volume warehouse, the right answer is normally a daily pickup and no API call; a pickup request is for retailers and marketplace sellers who ship in bursts.

Scheduling a pickup is not the same as closing out the day. Some carriers also need a manifest or end-of-day close so the driver can scan a single document — see End of Day.

What each carrier supports#

A dash means RocketShipIt does not implement that call for the carrier, usually because the carrier's own API does not offer it. Where a carrier supports neither status nor cancel, the carrier's own portal is the only way to change a booked pickup.

Times and dates#

Every carrier wants three things: the date, the time the packages are ready, and the time the location closes. The driver comes somewhere between the two, so a ready time later than the close time is rejected, and a narrow window gives the carrier less room to make the stop.

The formats differ by carrier and RocketShipIt passes them through:

FedEx combines pickup_date and ready_time into a single timestamp. If you send ready_time without pickup_date, the ready time is dropped and the pickup is booked for the next business day. Always send both. When close_time is omitted FedEx defaults to 17:00.

DHL Express defaults to today with a 10:20 ready time and a 16:20 close, and fills the pickup address in from the ship_* address when no pickup_* address is given. UPS defaults the date to today.

Cancelling a pickup#

Cancelling needs more than the confirmation number on most carriers. What each one requires:

Two traps live in that table.

FedEx defaults pickup_date to today when you cancel. A pickup booked for Thursday cannot be cancelled with a Wednesday request; send the date the pickup was scheduled for. Note the format flips: createpickup takes 20260115 and cancelpickup takes 2026-01-15.

FedEx Express cancels need the location code, the identifier of the FedEx Express station handling the pickup (LOSA and the like). It is returned as location in the createpickup response and is not derivable from anything else, so store it next to the confirmation number. Ground (FDXG) cancels do not need it. carrier_code defaults to FDXG; pass FDXE for Express on both the create and the cancel, and make sure the two match.

Pricing a pickup before you book it#

UPS charges for an on-call pickup and will quote it first:

{
  "carrier": "UPS-REST",
  "action": "pickuprate",
  "params": {
    "key": "your-key-from-authenticate-request",
    "pickup_addr1": "940 Presidio Ave",
    "pickup_city": "San Francisco",
    "pickup_state": "CA",
    "pickup_code": "94115",
    "pickup_country": "US",
    "pickup_date": "20260115",
    "ready_time": "0800",
    "close_time": "1700"
  }
}

The response is {"total_charge": 7.40, "errors": []}. RocketShipIt also sets UPS's rate indicator on createpickup, so a successful booking returns the same figure in charge without a second call — pickuprate is for showing a price before committing.

Checking what is already booked#

pickupstatus lists the pickups pending on an account. UPS takes an optional pickup_type of oncall, smart or both (the default):

{
  "carrier": "UPS-REST",
  "action": "pickupstatus",
  "params": {
    "key": "your-key-from-authenticate-request",
    "pickup_type": "oncall"
  }
}

Each entry carries pickup_id, status_code, description, contact and reference_number. It is the cheapest way to answer "did that booking actually go through" without storing anything yourself, and the only way to recover a confirmation number you failed to store — on UPS and Canada Post. No other carrier here offers it.

Carrier notes#

UPS#

• pickup_service_code is the UPS service being collected and pickup_container_code the packaging: 01 package, 02 UPS letter, 03 pallet. For a mixed load send a packages array instead and set service, pieces and packaging_type per entry.
• UPS truncates silently, so keep values short: company and contact names to 25 characters, pickup_location to 25, special_instructions to 57 and reference_number to 35. RocketShipIt truncates to those limits before sending rather than letting UPS reject the request.
• pickup_location shows as Preferred Location in the UPS portal — "Front desk", "Loading dock", "Side door".
• pickup_email gets the confirmation mail; to_email is used if it is unset.
• pickup_room, pickup_floor and pickup_residential are honoured, which matters for an apartment or an office in a shared building.

FedEx#

• carrier_code selects the FedEx operating company: FDXG (Ground, the default) or FDXE (Express). They are booked and cancelled separately, so a day with both Ground and Express packages needs two pickup requests.
• pickup_package_location tells the driver where to look. FedEx accepts FRONT, REAR, SIDE and NONE, and RocketShipIt sends NONE when the parameter is unset.
• weight and package_count describe the whole pickup, not one parcel. package_count defaults to 1.
• Setting freight_account_number routes createpickup and cancelpickup to the FedEx Freight LTL pickup API instead, where each entry in packages becomes a handling unit. See FedEx Freight.

DHL Express#

• The pickup address falls back to the ship_* address, so a shipment that goes out from where it was created needs no pickup_* address at all.
• packages sets the piece count and total weight on the booking — send the same array you sent to submitshipment.
• A pickup for today and a pickup for a future date are different request types to DHL. RocketShipIt picks the right one from pickup_date.
• Cancelling needs the confirmation number and the date and country of the pickup.

DHL-PL#

DHL Parcel Poland books a pickup for shipments that already exist, so it takes shipment_ids rather than an address:

{
  "carrier": "DHL-PL",
  "action": "createpickup",
  "params": {
    "username": "YOUR_USERNAME",
    "password": "YOUR_PASSWORD",
    "shipment_ids": ["90000019278"],
    "pickup_date": "2026-01-15",
    "ready_time": "08:00",
    "close_time": "16:00"
  }
}

Stamps.com (USPS)#

USPS package pickup is free, and the request is about telling the mail carrier where to look rather than dispatching a driver:

• pickup_total_weight — total pounds being collected
• pickup_location — where the packages are ("Front door", "Mail room")
• number_of_priority_mail_pieces — piece count by mail class
• special_instructions — anything else the carrier needs

Canada Post#

account_number is your Canada Post customer number and identifies the account the pickup is booked against. The returned pickup_id is the pickup request ID, and pickupstatus lists outstanding requests for the account.

Examples#

• UPS-REST - Pickup Schedule
• UPS-REST - Pickup Rate
• UPS-REST - Pickup Status
• UPS-REST - Pickup Cancel
• FedEx-REST - Pickup Ground
• FedEx-REST - Pickup Express
• FedEx-REST - Pickup Cancel
• FedEx-REST - Freight Pickup
• DHL - Pickup Schedule
• DHL - Pickup Cancel
• DHL-PL - Pickup
• Canada Post - Pickup Schedule
• Stamps.com - Pickup Schedule
• OnTrac - Pickup

Every pickup parameter is listed in Parameters.