v1

latestOpenAPI 3.1.02026-07-2277219695.0 KB

Pickups

Create a pickup

Creates a pickup object. This request is for a carrier to come to a specified location to take a package for shipping.

post/pickups

Headers

SHIPPO-API-VERSIONstring

Example:2018-02-08

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

Request body

carrier_accountstring 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.

metadatastring

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

requested_end_timestring 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_timestring date-time required

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

transactionsstring[] required

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

Example request

{
  "carrier_account": "adcfdddf8ec64b84ad22772bce3ea37a",
  "location": {
    "address": {
      "name": "Shwan Ippotle",
      "company": "Shippo",
      "street1": "215 Clayton St.",
      "city": "San Francisco",
      "state": "CA",
      "zip": "94117",
      "country": "US",
      "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"
  },
  "transactions": [
    "adcfdddf8ec64b84ad22772bce3ea37a"
  ]
}

Response

Pickup

carrier_accountstring 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.

metadatastring

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

requested_end_timestring 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_timestring date-time required

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

transactionsstring[] required

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

object_createdstring date-time

Date and time of Pickup creation.

object_idstring

Unique identifier of the given Pickup object.

object_updatedstring date-time

Date and time of last Pickup update.

confirmed_start_timestring datetime

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

confirmed_end_timestring datetime

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

cancel_by_timestring 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.

status'PENDING' | 'CONFIRMED' | 'ERROR' | 'CANCELLED'

Indicates the status of the pickup.

confirmation_codestring

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.

timezonestring

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

messagesstring[]

An array containing strings of any messages generated during validation.

is_testboolean

Indicates whether the object has been created in test mode.

Example response

{
  "carrier_account": "adcfdddf8ec64b84ad22772bce3ea37a",
  "location": {
    "address": {
      "name": "Shwan Ippotle",
      "company": "Shippo",
      "street1": "215 Clayton St.",
      "city": "San Francisco",
      "state": "CA",
      "zip": "94117",
      "country": "US",
      "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"
  },
  "transactions": [
    "adcfdddf8ec64b84ad22772bce3ea37a"
  ],
  "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": []
}