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 Returns

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

Considerations¶

USPS will pick up a merchant’s packages on the next USPS delivery day (Monday thru Saturday, excluding holidays) for free.
Pickup requests and cancellations must be submitted before 3:00 AM EST on the day of pickup.
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.
The request must have at least one package that uses one of the following services:
- Priority Mail.
- Priority Mail Express.
- A Returns Service.
- An International Service. Use INT as the serviceId when using an international service.
The following address fields are required in the pickupAddress object:
- addressLines
- cityTown
- stateProvince
- postalCode
- countryCode
- company
- name
- phone (maximum 10 digits)
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
Package pickup is available only for domestic addresses.

Request URLs¶

Sandbox: https://shipping-api-sandbox.pitneybowes.com/shippingservices/v1/pickups/schedule
Production: https://shipping-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. The following characters are allowed: letters, numbers, hyphens (`-`), and underscores (`_`). Important: 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¶

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[Pickup Summary Object]	Required. Each object in the array describes the count and total weight of the parcels for a specific service type.
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 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.

Pickup Summary Object¶

The pickupSummary array takes the pickup summary object.

Name	Data Type	Description
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.
totalWeight.weight	Number, up to 2 decimal places	Required. The total weight in ounces for all the parcels for this service type.
totalWeight.unitOfMeasurement	String	Required. The unit of measurement. Set this to: `OZ`
serviceId	String	Required. The service type. Valid values are: `UGA`: USPS Ground Advantage `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.

Sample Requests¶

See the following examples:

Sample Pickup Request for Delivery Shipments Only
Sample Pickup Request that Includes Returns Shipments

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-555-0000",
        "taxId": "12345678"
    },
    "carrier": "USPS",
    "pickupSummary": [ {
        "totalWeight": {
            "unitOfMeasurement": "OZ",
            "weight": "12"
        },
        "serviceId": "PM",
        "count": 20
    },{
        "totalWeight": {
            "unitOfMeasurement": "OZ",
            "weight": "10"
        },
        "serviceId": "UGA",
        "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-555-0000",
        "taxId": "12345678"
    },
    "carrier": "USPS",
    "pickupSummary": [ {
        "returnShipment": false,
        "totalWeight": {
            "weight": 12.0,
            "unitOfMeasurement": "OZ"
        },
        "serviceId": "PM",
        "count": 20
    },{
        "returnShipment": false,
        "totalWeight": {
            "weight": 10.0,
            "unitOfMeasurement": "OZ"
        },
        "serviceId": "UGA",
        "count": 40
    },
    ...
    ],
    "packageLocation": "Knock on Door/Ring Bell",
    "pickupDateTime": "02/22/2022",
    "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-555-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-555-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/2022",
    "pickupConfirmationNumber": "WTC61170430",
    "pickupId": "USPS1JEO9X9399KQG",
    "pickupOptions": []
}

Error Codes¶

For a list of all error codes returned by the Ecommerce APIs, please see Error Codes.