Skip to main content
POST
/
pickups
cURL
curl https://api.goshippo.com/pickups/  \
-H "Authorization: ShippoToken <API_TOKEN>" \
-H "Content-Type: application/json"  \
-d '{
      "carrier_account":"6c51273296864869829b96a80fb13ea1",
      "location":{
              "building_location_type": "Other",
              "building_type": "suite",
              "instructions": "Behind screen door",
              "address": {
                      "name": "Mrs Hippo",
                      "company": "Hungry Hippos",
                      "street1": "965 Mission St #201",
                      "city": "San Francisco",
                      "state": "CA",
                      "zip": "95122",
                      "country": "US",
                      "phone": "+14159876543",
                      "email": "mrshippo@shippo.com"
                  }
      },
      "transactions": ["7439c279b374494c9a80ca24f59e6fc5"],
      "requested_start_time":"2020-05-12T12:00:00Z",
      "requested_end_time": "2020-05-12T16:00:00Z",
      "metadata": "Customer ID 123456",
      "is_test": false
    }'
{
  "carrier_account": "adcfdddf8ec64b84ad22772bce3ea37a",
  "location": {
    "address": {
      "name": "Shwan Ippotle",
      "street1": "215 Clayton St.",
      "city": "San Francisco",
      "state": "CA",
      "zip": "94117",
      "country": "US",
      "company": "Shippo",
      "street2": "<string>",
      "street3": "",
      "street_no": "",
      "phone": "+1 555 341 9393",
      "email": "shippotle@shippo.com",
      "is_residential": true,
      "metadata": "Customer ID 123456",
      "validate": true
    },
    "building_location_type": "Front Door",
    "building_type": "apartment",
    "instructions": "Behind screen door"
  },
  "requested_end_time": "2023-11-07T05:31:56Z",
  "requested_start_time": "2023-11-07T05:31:56Z",
  "transactions": [
    "adcfdddf8ec64b84ad22772bce3ea37a"
  ],
  "metadata": "<string>",
  "object_created": "2023-11-07T05:31:56Z",
  "object_id": "<string>",
  "object_updated": "2023-11-07T05:31:56Z",
  "confirmed_start_time": "2020-05-09T12:00:00Z",
  "confirmed_end_time": "2020-05-09T23:59:59.999Z",
  "cancel_by_time": "2020-05-09T08:00:00Z",
  "status": "CONFIRMED",
  "confirmation_code": "WTC310058750",
  "timezone": "US/Pacific",
  "messages": [],
  "is_test": true
}

Authorizations

​
Authorization
string
header
default:ShippoToken shippo_test_d41a6f04796998570c521a50828eae8e3cccf0eb
required

API key authentication using the ShippoToken scheme. Format: Authorization: ShippoToken <API_TOKEN> Example: Authorization: ShippoToken shippo_live_abc123

Headers

​
SHIPPO-API-VERSION
string
default:2018-02-08

Optional string used to pick a non-default API version to use. See our API version guide.

Example:

"2018-02-08"

Body

application/json

Shippo’s pickups endpoint allows you to schedule pickups with USPS and DHL Express for eligible shipments that you have already created.

​
carrier_account
string
required

The object ID of your USPS or DHL Express carrier account. You can retrieve this from your Rate requests or our Carrier Accounts endpoint.

Example:

"adcfdddf8ec64b84ad22772bce3ea37a"

​
location
object
required

Location where the parcel(s) will be picked up.

​
requested_end_time
string<date-time>
required

The latest that you requested your parcels to be available for pickup. Expressed in the timezone specified in the response.

​
requested_start_time
string<date-time>
required

The earliest that you requested your parcels to be ready for pickup. Expressed in the timezone specified in the response.

​
transactions
string[]
required

The transaction(s) object ID(s) for the parcel(s) that need to be picked up.

Example:
["adcfdddf8ec64b84ad22772bce3ea37a"]
​
metadata
string

A string of up to 100 characters that can be filled with any additional information you want to attach to the object.

Response

Pickup

​
carrier_account
string
required

The object ID of your USPS or DHL Express carrier account. You can retrieve this from your Rate requests or our Carrier Accounts endpoint.

Example:

"adcfdddf8ec64b84ad22772bce3ea37a"

​
location
object
required

Location where the parcel(s) will be picked up.

​
requested_end_time
string<date-time>
required

The latest that you requested your parcels to be available for pickup. Expressed in the timezone specified in the response.

​
requested_start_time
string<date-time>
required

The earliest that you requested your parcels to be ready for pickup. Expressed in the timezone specified in the response.

​
transactions
string[]
required

The transaction(s) object ID(s) for the parcel(s) that need to be picked up.

Example:
["adcfdddf8ec64b84ad22772bce3ea37a"]
​
metadata
string

A string of up to 100 characters that can be filled with any additional information you want to attach to the object.

​
object_created
string<date-time>

Date and time of Pickup creation.

​
object_id
string

Unique identifier of the given Pickup object.

​
object_updated
string<date-time>

Date and time of last Pickup update.

​
confirmed_start_time
string<datetime>

The earliest that your parcels will be ready for pickup, confirmed by the carrier. Expressed in the timezone specified in the response.

Example:

"2020-05-09T12:00:00Z"

​
confirmed_end_time
string<datetime>

The latest that your parcels will be available for pickup, confirmed by the carrier. Expressed in the timezone specified in the response.

Example:

"2020-05-09T23:59:59.999Z"

​
cancel_by_time
string<datetime>

The latest time to cancel a pickup. Expressed in the timezone specified in the response. To cancel a pickup, you will need to contact the carrier directly. The ability to cancel a pickup through Shippo may be released in future iterations.

Example:

"2020-05-09T08:00:00Z"

​
status
enum<string>

Indicates the status of the pickup.

Available options:
PENDING,
CONFIRMED,
ERROR,
CANCELLED
Example:

"CONFIRMED"

​
confirmation_code
string

Pickup's confirmation code returned by the carrier. To edit or cancel a pickup, you will need to contact USPS or DHL Express directly and provide your confirmation_code.

Example:

"WTC310058750"

​
timezone
string

The pickup time windows will be in the time zone specified here, not UTC.

Example:

"US/Pacific"

​
messages
string[]

An array containing strings of any messages generated during validation.

Example:
[]
​
is_test
boolean

Indicates whether the object has been created in test mode.