# Schedule pickup

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.

Endpoint: POST /api/shipment/pickup/add
Version: v2
Security: BearerAuth

## Request fields (application/json):

  - `pickup_date` (string)
    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_location` (object)

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

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

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

  - `pickup_location.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

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

  - `pickup_location.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"

  - `pickup_location.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"

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

  - `pickup_location.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"

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

  - `pickup_location.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"

  - `pickup_location.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"

  - `package_location` (array, 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_ext` (string)
    Additional details on where the packages can be picked-up. This is required when the package_location is other.

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

  - `tracking_nos` (array, required)
    A list of shipment tracking numbers associated with the packages to be included in the pickup request.
    Example: ["9234690381085700XXXXX"]

## Response 200 fields (application/json):

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

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

  - `data` (object)

  - `data.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_date` (string)
    Scheduled pickup date (YYYY-MM-DD).
    Example: "2025-11-21"

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

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

  - `data.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.carrier_name` (string)
    Name of the carrier handling the pickup.
    Example: "USPS"

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