Schedule a Pickup

HTTP Request

POST /v1/pickups/schedule

Summary

This operation schedules a USPS package pickup from a residential or commercial location and provides a pickup confirmation number.

Things to Consider

  1. USPS will pick up a merchant’s packages on the next USPS delivery day (Monday thru Saturday, excluding holidays) for free.

  2. Pickup requests and cancellations must be submitted before 3:00 AM EST on the day of pickup.

  3. Before you schedule a pickup, it is recommended you use USPS’s Package Pickup Availability Web Tool to confirm that service to the pickup address is available.

  4. For a valid request, you must have at least one of the following: a Priority Mail Express package, a Priority Mail package, or an international package.

  5. The address entered in the pickup request might look different in the pickup response. This is because USPS standardizes and verifies addresses to make certain that carriers can find the pickup location.

    For example, this request:

    ABC Movers
    1500 East Main Avenue, Suite 201
    Springfield, VA 22162

    Returns this response:

    ABC MOVERS
    1500 E MAIN AVE STE 201
    SPRINGFIELD, VA 22162-1010

  6. Package pickup is available only for domestic addresses.

Request URIs

Sandbox: https://api-sandbox.pitneybowes.com/shippingservices/v1/pickups/schedule
Production: https://api.pitneybowes.com/shippingservices/v1/pickups/schedule

Request Headers

Name Data Type Description
Authorization String Required. OAuth token generated using the Generate an OAuth Token API.
Content-Type String Required. The media type of the request entity. Set this to application/json.

Request / Response Elements

The API call sends and receives a pickup object.

Name Data Type Description
pickupAddress address object Required. Pickup Address.
carrier String Required. The carrier for which a pickup is being requested. Set this to: USPS
pickupSummary Array[Object] Required. Each object in the array describes the count and total weight of the parcels for a specific service type.
    serviceId String

Required. The service type. Valid values are:

  • FCM: First-Class Mail
  • PM: Priority Mail
  • EM: Priority Mail Express
  • PRCLSEL: Parcel Select
  • INT: Indicates one of the following international services: First-Class Mail International; First-Class Package International Service; Priority Mail Express International; Priority Mail International
  • OTH: Other Packages
    count Number Required. The number of parcels for the service type. This field is used only in the request and is not returned in the response.
    totalWeight Object Required. The total weight for all the parcels for this service type.
            weight Number, up to 2 decimal places Required. The total weight for all the parcels for this service type.
            unitOfMeasurement String Required. The unit of measurement.
reference String  
packageLocation String

Required. The location of the parcel at the pickup location. Valid values are:

  • Front Door
  • Back Door
  • Side Door
  • Knock on Door/Ring Bell
  • Mail Room
  • Office
  • Reception
  • In/At Mailbox
  • Other
specialInstructions String

Instructions for picking up the parcel.

Required if packageLocation is set to Other.

pickupDateTime String Response Only. Scheduled date of the pickup.
pickupConfirmationNumber String Response Only. A confirmation number for the pickup.
pickupId String Response Only. The pickup ID. You must specify this ID if canceling the pickup.

Sample Request

curl -X POST .../v1/pickups/schedule \
–H "Authorization: Bearer <oauth_token>" \
-H "Content-Type: application/json" \
–H "X-PB-TransactionId: <unique_transaction_id>" \
-d '
{
    "pickupAddress": {
        "addressLines": [
            "3001 Summer Street",
            "",
            ""
        ],
        "cityTown": "STAMFORD",
        "stateProvince": "CT",
        "postalCode": "06905",
        "countryCode": "US",
        "company": "Pitney Bowes Inc",
        "name": "John Smith",
        "phone": "203-555-1220",
        "email": "jsmith@example.net",
        "residential": false,
        "taxId": "12345678"
    },
    "carrier": "usps",
    "pickupSummary": [ {
        "serviceId": "INT",
        "count": 9,
        "totalWeight": {
            "unitOfMeasurement": "OZ",
            "weight": "480"
        }
    }, ... ],
    "reference": "example_reference",
    "packageLocation": "Front Door",
    "specialInstructions": "Example Instructions"
}'

Sample Response

{
    "pickupAddress": {
        "addressLines": [
            "3001 SUMMER ST STE 3"
        ],
        "cityTown": "STAMFORD",
        "stateProvince": "CT",
        "postalCode": "06905",
        "countryCode": "US",
        "company": "PITNEY BOWES INC",
        "name": "John Smith",
        "phone": "203-555-1220",
        "email": "jsmith@example.net",
        "residential": false,
        "taxId": "12345678"
    },
    "carrier": "usps",
    "pickupSummary": [ {
        "totalWeight": {
            "weight": 480,
            "unitOfMeasurement": "OZ"
        },
        "serviceId": "INT"
    }, ... ],
    "reference": "example_reference",
    "packageLocation": "Front Door",
    "specialInstructions": "Example Instructions",
    "pickupDateTime": "07/22/2017",
    "pickupConfirmationNumber": "WTC58426418",
    "pickupId": "USPS1HRJ7YK55FUWM"
}

Error Codes

For a list of all PB Shipping APIs error codes, see Error Codes.