Skip to content
API Reference
/
/
Schedule pickup

Schedule pickup

Request

Create a USPS Carrier Pickup request using existing shipment information. This endpoint schedules a postal carrier to pick up eligible packages on the next USPS delivery day. For all possible error codes returned by this endpoint, see Appendix – Pickup Error Codes.

Security
BearerAuth
Bodyapplication/jsonrequired
pickup_datestring

The scheduled pickup date in YYYY-MM-DD format. If omitted, the value is automatically set to the next calendar day based on the America/Los_Angeles time zone, regardless of the request submission time.

pickup_locationobject(PickupAddress)
Any of:
package_locationstring(PackageLocationEnum)required

This is the location of the packages ready for pick-up at the pickup address.

Enum:"front_door""back_door""side_door""knock_on_door_ring_bell""mail_room""office""reception""in_at_mail_box""other"
package_location_extstring, <= 255 characters

Additional details on where the packages can be picked-up. This is required when the package_location is other. Chinese characters are not supported.

carrier_codestring(PickUpCarrierCodeEnum)required

A code identifying the shipping carrier/provider for the pickup. This value determines which logistics provider should handle the pickup or shipment request. Currently only USPS is supported. Future values may include codes for other carriers (e.g., UPS, FedEx).

Value:"USPS"
Example:"USPS"
tracking_nosArray of stringsrequired

A list of shipment tracking numbers associated with the packages to be included in the pickup request.

POST
/api/shipment/pickup/add
curl -i -X POST \
  https://x-api.shipsaving.com/api/shipment/pickup/add \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "pickup_date": "string",
    "pickup_location": {
      "first_name": "Alice",
      "last_name": "Green",
      "company_name": "ShipSaving",
      "phone": "1234567890",
      "email": "it@shipsaving.com",
      "street": "xxxx Olive Street",
      "street2": "STE XXX",
      "city": "San Francisco",
      "state": "CA",
      "zip_code": "941XX",
      "country": "US",
      "address_type": "residential"
    },
    "package_location": "front_door",
    "package_location_ext": "string",
    "carrier_code": "USPS",
    "tracking_nos": [
      "9234690381085700XXXXX"
    ]
  }'

Responses

OK

Bodyapplication/json
codestring
Example:"ok"
msgstring
Example:"ok"
dataobject(AddPickupResult)
Response
{
  "code": "ok",
  "msg": "ok",
  "data": {
    "pickup_no": "10000000000",
    "pickup_date": "2025-11-21",
    "package_total_num": 1,
    "package_total_weight": 0.1,
    "carrier_code": "USPS",
    "carrier_name": "USPS",
    "confirmation_number": "WTC65384000"
  }
}