# Retrieve pickup records

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.

Endpoint: GET /api/shipment/pickup/list
Version: v2
Security: BearerAuth

## Query parameters:

  - `confirmation_number` (string)
    This is the USPS assigned confirmation number of the pick-up.
    Example: "WTC65384000"

  - `status` (string)
    Pickup status filter.
    Enum: "CONFIRMED", "CANCELED"

  - `carrier_code` (string)
    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).
    Enum: "USPS"

  - `page` (integer)
    Page number for paginated results (starting from 1).

  - `page_size` (integer)
    Number of results to return per page.

  - `order_by` (boolean, required)
    Sorting flag that controls the time order:
  - true: chronological order (oldest → newest)
  - false: reverse chronological order (newest → oldest)

## Response 200 fields (application/json):

  - `code` (string)
    Example: "ok"

  - `msg` (string)
    Example: "ok"

  - `data` (object)

  - `data.pickup_data_list` (array)
    List of pickup order records.

  - `data.pickup_data_list.status` (string)
    The current status of the USPS pickup request.
    Enum: "CONFIRMED", "CANCELED"

  - `data.pickup_data_list.pickup_no` (string)
    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

  - `data.pickup_data_list.pickup_date` (string)
    Scheduled pickup date in YYYY-MM-DD format.
    Example: "2025-11-21"

  - `data.pickup_data_list.package_total_num` (integer)
    Total number of packages included in the pickup request.
    Example: 1

  - `data.pickup_data_list.package_total_weight` (number)
    Total weight of all packages in pounds (lb).
    Example: 0.1

  - `data.pickup_data_list.carrier_code` (string)
    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).
    Enum: "USPS"

  - `data.pickup_data_list.carrier_name` (string)
    Name of the carrier handling the pickup.
    Example: "USPS"

  - `data.pickup_data_list.confirmation_number` (string)
    This is the USPS assigned confirmation number of the pick-up.
    Example: "WTC65384000"

  - `data.pickup_data_list.pickup_location_ext` (object)

  - `data.pickup_data_list.pickup_location_ext.first_name` (string, required)
    First Name corresponding to the address. For the Batch Quick Rate API, this parameter is optional.
    Example: "Alice"

  - `data.pickup_data_list.pickup_location_ext.last_name` (string, required)
    Last Name corresponding to the address. For the Batch Quick Rate API, this parameter is optional.
    Example: "Green"

  - `data.pickup_data_list.pickup_location_ext.company_name` (string)
    Firm/business name corresponding to the address.
    Example: "ShipSaving"

  - `data.pickup_data_list.pickup_location_ext.phone` (string)
    Phone number of the sender/recipient. Required for international shipments. Providing a phone number is highly recommended for all shipments to ensure accurate delivery and facilitate carrier contact if needed.
    Example: 1234567890

  - `data.pickup_data_list.pickup_location_ext.email` (string)
    Email address of the sender/recipient. May be used by the carrier for delivery notifications or issue resolution.
    Example: "support@shipsaving.com"

  - `data.pickup_data_list.pickup_location_ext.street` (string, required)
    The number of a building along with the name of the road or street on which it is located.
    Example: "xxxx Olive Street"

  - `data.pickup_data_list.pickup_location_ext.street2` (string)
    The secondary unit designator, such as apartment(APT) or suite(STE) number, defining the exact location of the address within a building.
    Example: "STE XXX"

  - `data.pickup_data_list.pickup_location_ext.city` (string, required)
    This is the city name of the address.
    Example: "Los Angeles"

  - `data.pickup_data_list.pickup_location_ext.state` (string, required)
    - For U.S. addresses, this field must be a valid two-letter state code (e.g., "CA" for California, "NY" for New York).
- For non-U.S. addresses, there is no restriction on the value.
    Example: "CA"

  - `data.pickup_data_list.pickup_location_ext.zip_code` (string, required)
    Postal code of an Address.
    Example: "021XX"

  - `data.pickup_data_list.pickup_location_ext.country` (string, required)
    2-letter code for country. This field’s value will be an [ISO 3166-1 two-digit code](https://en.wikipedia.org/wiki/ISO_3166-1).
    Example: "US"

  - `data.pickup_data_list.pickup_location_ext.address_type` (string, required)
    Indicates whether the destination address is residential or commercial.
This flag is used to determine carrier-specific surcharges (e.g., UPS residential delivery fees).
    Enum: "residential", "commercial"

  - `data.pickup_data_list.package_location` (array)
    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"

  - `data.pickup_data_list.package_location_ext` (string)
    Additional information describing the package location.
    Example: "Left behind the plant"

  - `data.pickup_data_list.tracking_nos` (array)
    List of shipment tracking numbers associated with the pickup.
    Example: ["94055XXXXXXXXX123","92055XXXXXXXXX456"]

  - `data.total_count` (integer)
    Total number of pickup records matching the query.