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

  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:

  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://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

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.