DOCS
Ctrl K

REST API · Guide

Pickups & drop-off

Once labels are bought, either book a carrier to collect them or drop them at a counter. A pickup is booked per carrier and covers the labels you attach to it.

1. What can be booked

curl -s https://api.parcelhub.ca/v1/pickups/carriers -H "Authorization: Bearer $TOKEN"   # who can pick up
curl -s https://api.parcelhub.ca/v1/pickups/options -H "Authorization: Bearer $TOKEN"    # same-day open? cutoff hour
curl -s "https://api.parcelhub.ca/v1/pickups/cutoffs?postal_code=M5H1T1&province=ON&country=CA" -H "Authorization: Bearer $TOKEN"

A cutoff is the latest time to request a same-day pickup. After it, choose the next business day.

2. Quote the fee

curl -s https://api.parcelhub.ca/v1/pickups/quote -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' -d '{
  "carrier": "ups", "pickup_date": "2026-11-03",
  "address": { "name": "Warehouse", "street": "120 Adelaide St W", "city": "Toronto",
               "state": "ON", "postal_code": "M5H 1T1", "country": "CA", "phone": "4165550100" }
}'
# → fee, discount, tax and total. Nothing is booked.

3. Book it

Booking charges the pickup fee to the wallet and sends the request to the carrier.

curl -s https://api.parcelhub.ca/v1/pickups -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' -d '{
  "carrier": "ups", "pickup_date": "2026-11-03",
  "time_window_start": "13:00:00", "time_window_end": "17:00:00",
  "address": { … same as the quote … },
  "building_type": "Office", "pickup_location": "Reception",
  "instructions": "Buzz 204",
  "shipment_ids": ["<shipment id>", "<shipment id>"]
}'
  • Times are local to the pickup address (HH:MM:SS). A wide window is easier for the carrier to meet.
  • building_type: Office, Warehouse, Residential or Other.
  • Attach the labels of the carrier you are booking: the driver collects only their own parcels.
  • If the carrier refuses the booking, the pickup shows as an exception: fix the cause and POST /v1/pickups/{id}/retry (no new charge), or cancel it for a refund.

Change or cancel

# Add more labels to a booked pickup
curl -s https://api.parcelhub.ca/v1/pickups/$PICKUP/shipments -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' -d '{"shipment_ids":["…"]}'
# Take one off (the pickup stays booked; "empty": true if it was the last)
curl -s -X DELETE https://api.parcelhub.ca/v1/pickups/$PICKUP/shipments/$SHIPMENT -H "Authorization: Bearer $TOKEN"
# Cancel (refunds the fee to the wallet)
curl -s -X POST https://api.parcelhub.ca/v1/pickups/$PICKUP/cancel -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' -d '{}'

List pickups with GET /v1/pickups?tab=active (also history, exceptions, cancelled, archived, draft). Each has a /timeline.

Drop-off locations

Some rates can't be picked up (pickup_supported: false on the rate): drop those parcels at a counter. Dropping off costs nothing extra for any rate. Find the nearest counters:

curl -s "https://api.parcelhub.ca/v1/rates/dropoffs?address=120+Adelaide+St+W,+Toronto,+ON&carriers=canada_post,ups&limit=5" -H "Authorization: Bearer $TOKEN"