Schedule a Pickup

HTTP Request

POST /v1/pickups/schedule

Summary

This operation schedules a Pitney Bowes package pickup from a residential or commercial location and provides a pickup confirmation number. You can schedule pickups for the following types of shipments, and you can combine different types in a single pickup request:

  • PB Expedited Delivery
  • PB Expedited Returns
  • PB Standard Returns

When using this API, set the carrier field to USPS. The pickup is performed by USPS®.

Considerations

  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. The request must have at least one package that uses one of the following services:

    • Priority Mail (PM)

    • Priority Mail Express (EM)

    • One of the following international services:

      • First-Class Mail International
      • First-Class Package International Service
      • Priority Mail International
      • Priority Mail Express International

      Use INT as the serviceId when using an international service.

    • One of the following returns services:

      • First-Class Package Return Service (FCM)
      • Priority Mail Return Service (PM)
      • Ground Return Service (PRCLSEL)
  5. The following address fields are required in the pickupAddress object:

    • addressLines
    • cityTown
    • stateProvince
    • postalCode
    • countryCode
    • company
    • name
    • phone (maximum 10 digits)
  6. 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

  7. Package pickup is available only for domestic addresses.

Request URLs

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

Request Headers

Name
Description
Authorization Required. OAuth token generated using the Generate an OAuth Token API.
Content-Type Required. The media type of the request entity. Set this to application/json.
Accept-Language Language and country code. Default: en-US
X-PB-TransactionId

Required. A unique identifier for the transaction, up to 25 characters.

Important: You must ensure this is a unique id.

X-PB-UnifiedErrorStructure Recommended. Set this to true to use the standard error object if an error occurs.

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.
    returnShipment Boolean If set to true, indicates the shipment is a return shipment. The default value is false, which indicates a delivery shipment.
    totalWeight Object Required. The total weight in ounces for all the parcels for this service type.
            weight Number, up to 2 decimal places Required. The total weight in ounces for all the parcels for this service type.
            unitOfMeasurement String Required. The unit of measurement. Set this to: OZ
    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.
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 Conditional. Instructions for picking up the parcel. This is required if the 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.
pickupOptions Array[Object] Name-value pairs describing pickup options, if provided by the carrier.

Sample Requests

See the following examples:

Sample Pickup Request for Delivery Shipments Only

The following pickup request includes only delivery shipments:

curl -X POST .../v1/pickups/schedule \
-H "Authorization: Bearer <oauth_token>" \
-H "Content-Type: application/json" \
-H "X-PB-TransactionId: <unique_transaction_id>" \
-H "X-PB-UnifiedErrorStructure: true" \
-d '
{
    "pickupAddress": {
        "addressLines": [
            "27 Waterview Dr"
        ],
        "cityTown": "Shelton",
        "stateProvince": "CT",
        "postalCode": "06484",
        "countryCode": "US",
        "company": "Supplies",
        "name": "John Smith",
        "phone": "203-000-0000",
        "taxId": "12345678"
    },
    "carrier": "USPS",
    "pickupSummary": [ {
        "totalWeight": {
            "unitOfMeasurement": "OZ",
            "weight": "18"
        },
        "serviceId": "INT",
        "count": 20
    },{
        "totalWeight": {
            "unitOfMeasurement": "OZ",
            "weight": "12"
        },
        "serviceId": "INT",
        "count": 40
    }, ... ],
    "packageLocation": "Knock on Door/Ring Bell"
}'
Response for a Pickup Request for Delivery Shipments Only
{
    "pickupAddress": {
        "addressLines": [
            "27 WATERVIEW DR"
        ],
        "cityTown": "SHELTON",
        "stateProvince": "CT",
        "postalCode": "06484",
        "countryCode": "US",
        "company": "SUPPLIES",
        "name": "John Smith",
        "phone": "203-000-0000",
        "taxId": "12345678"
    },
    "carrier": "USPS",
    "pickupSummary": [ {
        "returnShipment": false,
        "totalWeight": {
            "weight": 18.0,
            "unitOfMeasurement": "OZ"
        },
        "serviceId": "INT",
        "count": 20
    },{
        "returnShipment": false,
        "totalWeight": {
            "weight": 12.0,
            "unitOfMeasurement": "OZ"
        },
        "serviceId": "INT",
        "count": 40
    }, ... ],
    "packageLocation": "Knock on Door/Ring Bell",
    "pickupDateTime": "02/22/2021",
    "pickupConfirmationNumber": "WTC58426418",
    "pickupId": "USPSR17B8P280H0Z",
    "pickupOptions": []
}

Sample Pickup Request that Includes Returns Shipments

The following is a pickup request that includes both returns and delivery shipments:

curl -X POST .../v1/pickups/schedule \
-H "Authorization: Bearer <oauth_token>" \
-H "Content-Type: application/json" \
-H "X-PB-TransactionId: <unique_transaction_id>" \
-H "X-PB-UnifiedErrorStructure: true" \
-d '
{
    "pickupAddress": {
        "addressLines": [
            "27 Waterview Dr"
        ],
        "cityTown": "Shelton",
        "stateProvince": "CT",
        "postalCode": "06484",
        "countryCode": "US",
        "company": "Supplies",
        "name": "John Smith",
        "phone": "203-000-0000",
        "taxId": "12345678"
    },
    "carrier": "USPS",
    "pickupSummary": [ {
        "returnShipment": true,
        "serviceId": "PRCLSEL",
        "count": 1,
        "totalWeight": {
            "unitOfMeasurement": "OZ",
            "weight": "32"
        }
    },{
        "returnShipment": false,
        "serviceId": "PM",
        "count": 8,
        "totalWeight": {
            "unitOfMeasurement": "OZ",
            "weight": "12"
        }
    }, ... ],
    "packageLocation": "Front Door"
}'
Response for a Pickup Request that Includes Returns
{
    "pickupAddress": {
        "addressLines": [
            "27 WATERVIEW DR"
        ],
        "cityTown": "SHELTON",
        "stateProvince": "CT",
        "postalCode": "06484",
        "countryCode": "US",
        "company": "SUPPLIES",
        "name": "John Smith",
        "phone": "203-000-0000",
        "taxId": "12345678"
    },
    "carrier": "USPS",
    "pickupSummary": [ {
        "returnShipment": true,
        "totalWeight": {
            "weight": 32.0,
            "unitOfMeasurement": "OZ"
        },
        "serviceId": "PRCLSEL",
        "count": 1
    },{
        "returnShipment": false,
        "totalWeight": {
            "weight": 12.0,
            "unitOfMeasurement": "OZ"
        },
        "serviceId": "PM",
        "count": 8
    }, ... ],
    "packageLocation": "Front Door",
    "specialInstructions": "Example Instructions",
    "pickupDateTime": "03/03/2021",
    "pickupConfirmationNumber": "WTC61170430",
    "pickupId": "USPS1JEO9X9399KQG",
    "pickupOptions": []
}

Error Codes

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