Skip to content
API Reference
/
/
Retrieve pickup records

ShipSaving New API (v2)

Overview
License
Apache 2.0
Languages
Servers
Production server
https://x-api.shipsaving.com

Authentication

Operations

Shipment

Operations

Tracking

Operations

Pickup

Operations

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.

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(AddressTo)
package_locationArray of strings(PackageLocationEnum)required

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

Items Enum"front_door""back_door""side_door""knock_on_door_ring_bell""mail_room""office""reception""in_at_mail_box""other"
package_location_extstring

Additional details on where the packages can be picked-up. This is required when the package_location is other.

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 strings(TrackingNo)required

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

Example: ["9234690381085700XXXXX"]
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": "support@shipsaving.com",
      "street": "xxxx Olive Street",
      "street2": "STE XXX",
      "city": "Los Angeles",
      "state": "CA",
      "zip_code": "021XX",
      "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
application/json
{
  "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"
  }
}

Cancel pickup

Request

Cancel a previously scheduled carrier pick up. A carrier pickup can no longer be updated or cancelled once cancelled. It requires no additional parameters other than the pickup_no. The status will change to CANCELED on success.

Security
BearerAuth
Bodyapplication/jsonrequired
pickup_nostring(PickUpNo)required

The internal pickup record number used to identify a previously scheduled USPS pickup request. This value is returned during the pickup creation process and must be provided to cancel the corresponding pickup order.

Example: 10000000000
curl -i -X POST \
  https://x-api.shipsaving.com/api/shipment/pickup/cancel \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "pickup_no": 10000000000
  }'

Responses

OK

Bodyapplication/json
codestring
Example: "ok"
msgstring
Example: "ok"
dataobject
Example: {}
Response
application/json
{
  "code": "ok",
  "msg": "ok",
  "data": {}
}

Retrieve pickup records

Request

Fetches a paginated list of pickup records created in the system. This endpoint supports optional filters such as USPS confirmation number, pickup status, and carrier code. Pagination parameters (page and page_size) allow controlling the size of the returned dataset, and the order_by flag determines the sorting order of the results.

Security
BearerAuth
Query
confirmation_numberstring(PickUpConfirmationNo)

This is the USPS assigned confirmation number of the pick-up.

Example: confirmation_number=WTC65384000
statusstring

Pickup status filter.

Enum"CONFIRMED""CANCELED"
carrier_codestring(PickUpCarrierCodeEnum)

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: carrier_code=USPS
pageinteger(int32)

Page number for paginated results (starting from 1).

Default 1
page_sizeinteger(int32)

Number of results to return per page.

Default 50
order_bybooleanrequired

Sorting flag that controls the time order:

  • true: chronological order (oldest → newest)
  • false: reverse chronological order (newest → oldest)
curl -i -X GET \
  'https://x-api.shipsaving.com/api/shipment/pickup/list?confirmation_number=WTC65384000&status=CONFIRMED&carrier_code=USPS&page=1&page_size=50&order_by=true' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

OK

Bodyapplication/json
codestring
Example: "ok"
msgstring
Example: "ok"
dataobject
Response
application/json
{
  "code": "ok",
  "msg": "ok",
  "data": {
    "pickup_data_list": [ … ],
    "total_count": 0
  }
}

Get package location

Request

Returns the list of valid package location enum values. These values indicate where the packages will be placed at the pickup address for the USPS carrier to retrieve during the scheduled pickup.

Security
BearerAuth
curl -i -X GET \
  https://x-api.shipsaving.com/api/shipment/pickup/package/location/list \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

OK

Bodyapplication/json
codestring
Example: "ok"
msgstring
Example: "ok"
dataArray of strings(PackageLocationEnum)
Items Enum"front_door""back_door""side_door""knock_on_door_ring_bell""mail_room""office""reception""in_at_mail_box""other"
Response
application/json
{
  "code": "ok",
  "msg": "ok",
  "data": [
    [ … ]
  ]
}

Address Validation

Operations
Copyright © 2026 ShipSaving. All Rights Reserved.